mirror of
https://github.com/johannesjo/super-productivity.git
synced 2026-07-17 16:37:43 +00:00
docs(sync): record fast-track simplification audit
Capture the read-only audit evidence and its verified and provisional risk/reward guides in one baseline-preserving changeset.
This commit is contained in:
Johannes Millan
parent
4519c5f4d3
commit
6756e9998c
8 changed files with 13652 additions and 0 deletions
606
docs/plans/2026-07-16-sync-simplification-audit.md
Normal file
606
docs/plans/2026-07-16-sync-simplification-audit.md
Normal file
|
|
@ -0,0 +1,606 @@
|
|||
# Sync System Simplification Audit Plan
|
||||
|
||||
**Status:** Proposed
|
||||
|
||||
**Date:** 2026-07-16
|
||||
|
||||
**Scope:** Evaluation first; this plan does not authorize source changes.
|
||||
|
||||
## Goal
|
||||
|
||||
Systematically inspect the entire sync system for opportunities to reduce
|
||||
maintenance cost, cognitive load, duplication, unnecessary abstractions, and
|
||||
maintained lines of code without weakening behavior, compatibility, privacy, or
|
||||
data-safety guarantees.
|
||||
|
||||
The output is a verified, deduplicated backlog of small simplification
|
||||
candidates. “Verified” means that an independent reviewer reproduced the
|
||||
evidence at the frozen baseline; it does not mean that a deletion is safe until
|
||||
the implementation tests pass. This is not a commitment to hit a percentage
|
||||
LOC target. Fewer lines are useful only when the result is easier to understand
|
||||
and preserves the same inputs, outputs, side effects, ordering, errors, wire
|
||||
formats, replay behavior, and recovery paths.
|
||||
|
||||
## Leanest starting point
|
||||
|
||||
Reuse and fact-check the existing
|
||||
[`sync-core-simplification-roadmap.md`](../long-term-plans/sync-core-simplification-roadmap.md)
|
||||
instead of starting with a new architecture. Treat the larger
|
||||
[`2026-07-03-sync-engine-extraction-plan.md`](2026-07-03-sync-engine-extraction-plan.md)
|
||||
as a conditional hypothesis: extraction into another package is justified only
|
||||
if a real second host or measured boundary problem warrants its additional API,
|
||||
migration, and compatibility surface.
|
||||
|
||||
Also deduplicate against
|
||||
[`2026-07-07-complete-architecture-review.md`](2026-07-07-complete-architecture-review.md)
|
||||
and existing issues before recording new work.
|
||||
|
||||
## Working baseline
|
||||
|
||||
These counts are deliberately approximate because existing reports use slightly
|
||||
different source filters. Wave A must produce one reproducible scope manifest
|
||||
and replace them with exact figures.
|
||||
|
||||
| Surface | Approximate production size | Approximate test size |
|
||||
| --- | ---: | ---: |
|
||||
| Client op-log | 44.7k TS LOC | 100.6k TS LOC |
|
||||
| Client sync shell | 7.0k TS LOC | 10.6k TS LOC |
|
||||
| `@sp/sync-core` | 3.9k TS LOC | 4.7k TS LOC |
|
||||
| `@sp/sync-providers` | 7.3k TS LOC | 6.7k TS LOC |
|
||||
| Shared schema | 1.0k TS LOC | 1.1k TS LOC |
|
||||
| SuperSync server | 12.4k TS LOC | 30.4k TS LOC |
|
||||
| Sync E2E | n/a | 90 specs, 253 tests, about 33k LOC |
|
||||
| Main E2E sync harness | n/a | about 5k LOC |
|
||||
| Sync documentation | about 8.2k Markdown LOC | n/a |
|
||||
|
||||
The production surface is therefore roughly 76k TS LOC, with well over twice
|
||||
that amount in automated tests. Test LOC is tracked separately and must not be
|
||||
reduced by deleting distinct failure scenarios.
|
||||
|
||||
Current investigation signals include several multi-state-machine files:
|
||||
|
||||
- `conflict-resolution.service.ts`: about 3,934 LOC
|
||||
- `file-based-sync-adapter.service.ts`: about 3,042 LOC
|
||||
- `operation-log-store.service.ts`: about 2,918 LOC
|
||||
- `operation-log-sync.service.ts`: about 2,491 LOC
|
||||
- `sync-wrapper.service.ts`: about 1,704 LOC
|
||||
- `data-repair.ts`: about 1,586 LOC
|
||||
|
||||
File size is a routing signal, not evidence that a split or deletion is safe.
|
||||
|
||||
## Scope
|
||||
|
||||
### In scope
|
||||
|
||||
- `src/app/op-log/**`
|
||||
- `src/app/imex/sync/**`
|
||||
- `packages/sync-core/**`
|
||||
- `packages/sync-providers/**`
|
||||
- Sync-related `packages/shared-schema/**`
|
||||
- Sync, storage, quota, snapshot, WebSocket, validation, and lifecycle code in
|
||||
`packages/super-sync-server/**`
|
||||
- Root-store meta-reducers, persistent actions, logical-day handling, hydration
|
||||
guards, platform bridges, and feature effects that participate in op capture
|
||||
or replay correctness
|
||||
- Sync settings, conflict review, encryption/restore UX, and provider wiring
|
||||
- Unit, integration, PostgreSQL, browser, WebDAV, and SuperSync E2E tests
|
||||
- Sync docs, diagrams, ADRs, lint rules, and CI path/test selection
|
||||
- Historical compatibility and migration code, for retention analysis only
|
||||
|
||||
### Perimeter-only review
|
||||
|
||||
- Calendar, issue-provider, plugin, Android, Electron, and Capacitor “sync” code
|
||||
is included only where it observes persistent actions, reacts to replay, or
|
||||
crosses a sync provider/platform boundary.
|
||||
- Server authentication and account lifecycle are included only where they
|
||||
affect sync authorization, credential preservation, reset, restore, account
|
||||
deletion, or storage ownership.
|
||||
|
||||
### Out of scope
|
||||
|
||||
- Unrelated feature refactors
|
||||
- Product behavior changes disguised as cleanup
|
||||
- New sync features or providers
|
||||
- New dependencies or custom audit infrastructure
|
||||
- Generated code, vendored/minified assets, immutable historical SQL migrations,
|
||||
and snapshots as LOC-reduction targets
|
||||
- Automatic issue creation, source edits, commits, pushes, or PRs during audit
|
||||
|
||||
## Non-negotiable invariants
|
||||
|
||||
Every agent brief must link findings to the applicable invariant ledger. At a
|
||||
minimum it must preserve:
|
||||
|
||||
1. One atomic persistent state transition produces one operation, and
|
||||
replayed/remote operations do not re-trigger local effects. Deliberately
|
||||
sequenced workflows documented by an ADR remain separate operations; in
|
||||
particular, project completion must retain the ADR #5 `N + 1` sequence.
|
||||
2. Persistent operation contents are append-only; only lifecycle metadata may
|
||||
advance in place.
|
||||
3. Snapshot plus tail replay is equivalent to the current state.
|
||||
4. Replay is deterministic, idempotent where required, and preserves operation
|
||||
and side-effect ordering.
|
||||
5. Multi-entity actions remain atomic where the domain requires atomicity.
|
||||
6. Vector-clock comparison, corruption handling, and pruning semantics remain
|
||||
client/server compatible.
|
||||
7. Full-state imports, backups, repairs, provider switches, and clean-slate
|
||||
operations retain their intentionally destructive filtering semantics.
|
||||
8. Conflict resolution converges across clients, including delete-wins,
|
||||
disjoint merge, archive, and partial/multi-entity cases.
|
||||
9. File-based conditional-write, revision, migration, and crash-recovery
|
||||
behavior remains provider-compatible.
|
||||
10. Encryption remains fail-closed; keys, payloads, credentials, and user
|
||||
content never leak to logs.
|
||||
11. Server sequence allocation, conflict detection, quota, cleanup, snapshots,
|
||||
and repair bases retain their transaction/causality guarantees.
|
||||
12. Old backups, wire formats, schema barriers, and migrations remain supported
|
||||
until an explicit version-support decision says otherwise.
|
||||
13. Core tracking and sync continue to work offline; online providers degrade
|
||||
gracefully.
|
||||
14. The audit and any resulting implementation add no analytics or tracking.
|
||||
15. User data remains local unless the user explicitly configures it to sync;
|
||||
logs, audit artifacts, and diagnostics contain no user content.
|
||||
16. Effects that react to user intent consume `LOCAL_ACTIONS`; selector-based
|
||||
effects use `skipDuringSyncWindow()`. `ALL_ACTIONS` remains restricted to
|
||||
op-log capture, and remote archive side effects stay in
|
||||
`ArchiveOperationHandler`.
|
||||
17. Bulk operation dispatch retains the post-loop event-loop yield that prevents
|
||||
rapid dispatches from losing state.
|
||||
18. Logical-day decisions flow through `DateService` or replay-safe offset
|
||||
arguments, and virtual `TODAY_TAG` membership is never persisted in task
|
||||
`tagIds`.
|
||||
19. Vector clocks retain the 20-entry limit and server-side ordering: detect
|
||||
conflicts before pruning and storage.
|
||||
|
||||
The canonical starting references are `docs/sync-and-op-log/`,
|
||||
`ARCHITECTURE-DECISIONS.md`, and `e2e/CLAUDE.md`. Documentation claims must be
|
||||
verified against code and tests rather than assumed true.
|
||||
|
||||
## Operating model: at least 67 agent runs
|
||||
|
||||
This is a minimum of 67 bounded agent runs, not 67 simultaneous editors. The
|
||||
actual count grows within frozen phase budgets with the number of candidates
|
||||
that pass triage: every such candidate gets its own independent verification
|
||||
run, and every sync-critical candidate gets two. Run each phase in batches that
|
||||
fit the available concurrency.
|
||||
|
||||
Discovery agents are read-only and return reports to one coordinator. Only the
|
||||
coordinator may update the local audit ledger; synthesis agents also return
|
||||
reports rather than editing shared files. The audit does not edit source,
|
||||
tests, configuration, or existing documentation.
|
||||
|
||||
The ledger lives under `docs/research/sync-simplification-audit/` and has five
|
||||
coordinator-owned files: `baseline.md`, `ownership.tsv`, `findings.md`,
|
||||
`verification.md`, and `retained.md`. This plain-text layout avoids custom
|
||||
infrastructure. Creating these audit artifacts requires separate authorization
|
||||
to execute this plan; this plan alone does not authorize any writes.
|
||||
|
||||
| Phase | Seed runs | Purpose |
|
||||
| --- | ---: | --- |
|
||||
| A. Baseline scouts | 7 | Freeze and independently reproduce scope, invariants, dependencies, tests, history, and prior work |
|
||||
| B. Domain audits | 38 | Inspect every owned subsystem with minimal overlap |
|
||||
| C. Cross-cutting audits | 8 | Find duplication and lifecycle issues that domain ownership can miss |
|
||||
| D. Triage and synthesis | 4 | Deduplicate, test-map, risk-classify, and admit candidates to verification |
|
||||
| E. Fresh-context verification | 8 | Initial capacity; expand to one run per admitted candidate and a second for sync-critical work |
|
||||
| F. Final synthesis | 2 | Sequence the independently verified register and challenge completeness |
|
||||
|
||||
### Baseline and run contract
|
||||
|
||||
A1 records a baseline ID containing the commit SHA, `git status --porcelain=v1`,
|
||||
a hash of the tracked diff, hashes of in-scope untracked files, and a hash of
|
||||
the scope manifest. A clean dedicated worktree at the pinned commit is
|
||||
preferred. If intentional uncommitted changes are included, they are part of
|
||||
the baseline and must remain byte-for-byte unchanged. Drift checks exclude only
|
||||
the coordinator-owned audit-artifact directory; that exclusion is recorded in
|
||||
the manifest and never applies to source, tests, configuration, or existing
|
||||
documentation.
|
||||
|
||||
Immediately after A1, the coordinator records explicit numeric ceilings for
|
||||
Wave A continuation runs and Wave B/C continuation runs based on the manifest.
|
||||
After Wave C, the coordinator freezes D1 slice capacity from immutable origin
|
||||
records; after D1 deduplication it freezes D2–D4 capacity from the deduplicated
|
||||
records. After Wave D, it freezes the Wave E budget from the admitted-candidate
|
||||
count, additional sync-critical reviewers, the eight-run minimum, and at most
|
||||
one re-verification allowance per candidate. After Wave E, it freezes any
|
||||
manifest-derived Wave F slice budget. Exceeding a frozen budget stops for
|
||||
explicit user approval; agent count never expands silently.
|
||||
|
||||
Every run except the A1 bootstrap must:
|
||||
|
||||
1. Confirm the baseline ID before reading evidence and return `STALE_BASELINE`
|
||||
if it differs.
|
||||
2. Have one primary assignment, inspect the contents of at most 60 total files,
|
||||
and return at most five candidates. A larger assignment returns
|
||||
`SPLIT_REQUIRED` with proposed child slices; each slice becomes an additional
|
||||
agent run.
|
||||
3. Cite reproducible search/test/history commands and their relevant results.
|
||||
4. Stop after 45 minutes and return a partial report plus `SPLIT_REQUIRED`.
|
||||
5. Return at most 4,000 words total, including candidate records and evidence
|
||||
excerpts.
|
||||
6. Make no source, test, config, documentation, GitHub, CI, branch, or remote
|
||||
changes.
|
||||
|
||||
The file cap includes production, tests, scripts, schemas, and docs that are
|
||||
substantively opened or examined. Any agent may mechanically enumerate, hash,
|
||||
count, and search repository-wide paths without loading their contents; its
|
||||
content inspection still has the same cap. Finding a sixth viable candidate
|
||||
also returns `SPLIT_REQUIRED`. Slices use stable sorted path ranges or explicit
|
||||
subsystem boundaries, never agent discretion alone. Agents may not omit files,
|
||||
behavior, or candidates because of a limit; they must request a split within
|
||||
the frozen budget.
|
||||
|
||||
### Command isolation
|
||||
|
||||
Audit agents default to read-only searches and history inspection. A test or
|
||||
other command that writes caches, reports, snapshots, databases, ports, or temp
|
||||
state may run only in an isolated worktree with a unique temp/database/port
|
||||
namespace and disposable local services. External endpoints are never used
|
||||
without separate explicit authorization; local services that cannot be
|
||||
isolated are serialized. Otherwise the agent inspects the test and records the
|
||||
future command without executing it. Every executing agent compares the
|
||||
baseline before and after its run; any unexpected audited-file or local-service
|
||||
drift invalidates its evidence.
|
||||
|
||||
## Wave A: baseline scouts
|
||||
|
||||
| ID | Assignment | Required artifact |
|
||||
| --- | --- | --- |
|
||||
| A1 | Scope and metric manifest | Baseline ID; reproducible file list and exclusions; source/test/docs LOC and file counts |
|
||||
| A1R | Independent baseline reproduction | Re-run A1’s recorded procedure, challenge exclusions/search closure, and either reproduce both hashes or stop the audit |
|
||||
| A2 | Invariant ledger | Invariant, canonical source, enforcing code/lint, proving tests, known residuals |
|
||||
| A3 | Dependency/API map | Package direction, app deep imports, cycles, public exports, registries, DI/providers, high fan-in/out |
|
||||
| A4 | Scenario/test map | Unit/integration/E2E coverage mapped to documented sync scenarios and providers |
|
||||
| A5 | History/compatibility ledger | Legacy path origin, last producer/consumer, rollout/support horizon, removal precondition |
|
||||
| A6 | Prior-work dedupe | Local plans/ADRs/completed work plus existing issues only when execution authorization includes read-only issue retrieval; otherwise record external issue coverage as a blocking gap |
|
||||
|
||||
### Wave A exit criteria
|
||||
|
||||
- A1 records its complete query lexicon, seed paths, forward/reverse import and
|
||||
registration-closure algorithm, terminal inclusion rules, and exclusions.
|
||||
Discovery follows DI/provider registrations, entity/action registries,
|
||||
serialized action/format strings, package exports, build scripts, lint rules,
|
||||
workflows, and the recorded sync-related search terms until a full pass adds
|
||||
no files. The resulting manifest—not the seed path list—is the denominator.
|
||||
- A1R runs independent negative searches for missed sync terms, registrations,
|
||||
serialized strings, and importers before Waves B–F may start.
|
||||
- Every in-scope file has exactly one primary domain owner.
|
||||
- Every load-bearing invariant has at least one enforcing code path and test, or
|
||||
is explicitly recorded as a gap.
|
||||
- Existing findings and plans are mapped before new findings are accepted.
|
||||
- Metrics can be regenerated without adding a dependency.
|
||||
- The baseline ID and scope-manifest hash can be reproduced by another agent.
|
||||
|
||||
## Wave B: domain audits
|
||||
|
||||
Each numbered ID is one independent read-only agent assignment. Within a range,
|
||||
the semicolon-separated domains map left-to-right to the numbered IDs; for
|
||||
example, B01 owns core contracts/entity registry and B04 owns archive
|
||||
application.
|
||||
|
||||
| IDs | Domain assignments |
|
||||
| --- | --- |
|
||||
| B01–B04 | Core contracts/entity registry; capture/meta-reducer path; operation conversion/bulk apply; archive application |
|
||||
| B05–B09 | Operation-log store; IndexedDB/schema/upgrades; SQLite/backend migration; hydration/recovery; snapshots/compaction |
|
||||
| B10–B12 | Backup/legacy migration/clean slate; structural validation; repair algorithms/orchestration |
|
||||
| B13–B17 | Sync wrapper/triggers/status; main orchestrator/session guards; download/pagination; upload/write flush; remote/rejected/superseded ops |
|
||||
| B18–B22 | Conflict engine; conflict journal/review UI; vector clocks/import filtering; full-state/server migration; encryption/password/restore |
|
||||
| B23–B28 | Provider host/credentials/OAuth; file-based adapter/envelope; WebDAV/Nextcloud; Dropbox; OneDrive/LocalFile/platform; SuperSync client/WebSocket |
|
||||
| B29–B31 | `sync-core` algorithms/public API; `sync-providers` shared infrastructure; shared-schema HTTP contracts/migrations |
|
||||
| B32–B34 | Server upload/conflict transaction; server download/snapshot/cleanup/quota; server WebSocket/rate/dedup/validation/sync lifecycle |
|
||||
| B35 | Platform/perimeter sync correctness: root store, feature effects, logical day, Android/Electron/Capacitor bridges |
|
||||
| B36 | Unit/integration/E2E harness ownership and execution topology |
|
||||
| B37 | Sync lint rules, build scripts, package exports, CI selection, and scheduled-workflow reachability |
|
||||
| B38 | Prisma schema/indexes, database bootstrap/upgrade tooling, operational backup/recovery, and immutable migration inventory |
|
||||
|
||||
Each domain agent must:
|
||||
|
||||
1. Read the governing docs and neighboring implementation.
|
||||
2. Identify responsibilities, entry points, callers, outputs, persistent/wire
|
||||
shapes, platform branches, and error paths.
|
||||
3. Inspect matching unit/integration/E2E tests.
|
||||
4. Check relevant git history before proposing removal or consolidation.
|
||||
5. Return no more than five evidence-backed candidates plus an explicit “retain”
|
||||
list for complexity that is necessary.
|
||||
6. Avoid proposing a new abstraction unless it demonstrably removes more
|
||||
concepts, branches, or duplication than it adds.
|
||||
|
||||
### Wave B exit criteria
|
||||
|
||||
- Every manifest entry has one completed primary-domain report, including all
|
||||
required child slices. A recorded but unfinished `SPLIT_REQUIRED` run blocks
|
||||
the phase; if the frozen budget cannot cover it, stop for approval.
|
||||
- Each report covers callers, runtime registrations, persisted strings/formats,
|
||||
tests, history, and necessary complexity—not just static imports.
|
||||
- Every candidate satisfies the finding contract; unsupported observations are
|
||||
retained as questions, not promoted.
|
||||
|
||||
## Wave C: cross-cutting audits
|
||||
|
||||
| ID | Pattern audit |
|
||||
| --- | --- |
|
||||
| C1 | Dead exports, unused methods, deprecated aliases, no-value wrappers, and pass-through facades |
|
||||
| C2 | Duplicate result types, optional-field flag bags, state-machine branches, and status ownership |
|
||||
| C3 | Compatibility paths, migrations, format versions, feature flags, and rollout completion conditions |
|
||||
| C4 | Dependency cycles, facade bypasses, package ownership, deep imports, and public surface area |
|
||||
| C5 | Provider HTTP/auth/retry/error/logging duplication, separating genuinely shared behavior from protocol quirks |
|
||||
| C6 | Unit/integration/E2E duplication, fixtures, fixed waits, direct locators, flakiness, and runtime cost |
|
||||
| C7 | Documentation/diagram/ADR/scenario drift and opportunities for one canonical source plus generated links |
|
||||
| C8 | Privacy-safe logging, constants/configuration drift, error taxonomies, and platform branching |
|
||||
|
||||
Cross-cutting agents reference the primary domain owner instead of filing a
|
||||
second finding. The dedupe key is the same invariant, same mechanism, and
|
||||
overlapping files—not merely similar wording.
|
||||
|
||||
### Wave C exit criteria
|
||||
|
||||
- All eight pattern reports and all required child slices cover the complete A1
|
||||
manifest. An unfinished slice blocks the phase; if the frozen budget cannot
|
||||
cover it, stop for approval.
|
||||
- Cross-domain observations are linked to immutable origin IDs/dedupe keys or
|
||||
recorded in the retain register; no duplicate candidate advances
|
||||
independently.
|
||||
|
||||
## Finding contract
|
||||
|
||||
Every candidate uses this record:
|
||||
|
||||
```text
|
||||
Immutable origin ID / stable ID assigned by D1 / dedupe key / status
|
||||
Baseline ID / origin run / candidate-record revision hash
|
||||
Primary domain / related domains
|
||||
Title and category
|
||||
Exact paths and lines
|
||||
Current responsibility and why it may exist
|
||||
Callers, consumers, exports, and persisted/wire-format impact
|
||||
Duplicate or unnecessary mechanism
|
||||
Smallest proposed simplification
|
||||
Behavioral-equivalence argument
|
||||
Protected invariants and failure modes
|
||||
Evidence commands and relevant results
|
||||
Git/history/rollout/support evidence
|
||||
Existing issue/plan overlap
|
||||
Required characterization and verification tests
|
||||
Estimated production/test/docs LOC delta
|
||||
Maintenance/cognitive-load reduction
|
||||
Blast radius and reversibility
|
||||
Risk: low / medium / high / sync-critical
|
||||
Evidence confidence: weak / supported / reproduced
|
||||
Verifier IDs / challenges / disposition / decision rationale
|
||||
Recommendation: pursue / investigate / retain / already tracked / decision required
|
||||
```
|
||||
|
||||
A stable dedupe key combines the protected invariant, current mechanism, and
|
||||
overlapping files. Discovery assigns origin IDs such as `B13-C03`; Wave C uses
|
||||
origin IDs and dedupe keys, and D1 maps them to stable IDs without overwriting
|
||||
their provenance. Candidate states are:
|
||||
|
||||
```text
|
||||
proposed → triaged → verification-ready → verified
|
||||
↘ rejected / decision-required
|
||||
proposed or triaged → already-tracked / retained
|
||||
```
|
||||
|
||||
The audit may label a hypothesis `verified`; it never labels a deletion
|
||||
“proven.” Static call-site search can miss dynamic lookup, dependency injection,
|
||||
serialized action names, persisted formats, plugin consumers, older clients,
|
||||
and behavior absent from tests. A deletion is safe only after those consumers
|
||||
are checked, compatibility is decided, and the eventual implementation passes
|
||||
the behavior-preserving verification ladder. “Large file,” “many branches,” or
|
||||
“high LOC” alone is not a finding.
|
||||
|
||||
## Wave D: triage before verification
|
||||
|
||||
Triage happens after discovery and before any verifier is assigned.
|
||||
|
||||
| ID | Responsibility |
|
||||
| --- | --- |
|
||||
| D1 | Finding librarian: assign stable IDs, merge dedupe keys, and link prior work |
|
||||
| D2 | Invariant/risk classifier: reject behavioral changes disguised as simplification |
|
||||
| D3 | Evidence and test mapper: require reproducible commands and characterization paths |
|
||||
| D4 | Benefit/cost classifier: apply the rubric and admit verification-ready candidates |
|
||||
|
||||
The coordinator applies D1–D4 reports in that order. An admitted candidate has
|
||||
one immutable revision hash. Any material edit after admission creates a new
|
||||
revision that must be verified again. D3 must decompose a proposal into smaller
|
||||
independently safe candidates, or mark it `decision-required`, when its complete
|
||||
consumer/registration/format/test verification closure cannot fit within one
|
||||
verifier’s 60-file and time limits.
|
||||
|
||||
### Candidate classification rubric
|
||||
|
||||
Do not calculate a synthetic numerical score. Record four independent bands:
|
||||
|
||||
| Dimension | Bands |
|
||||
| --- | --- |
|
||||
| Maintenance benefit | High: removes a policy/state owner or repeated lifecycle; medium: removes meaningful duplication/branching; low: mostly cosmetic |
|
||||
| Evidence confidence | Reproduced: commands/results independently repeat; supported: multiple code/test/history sources agree; weak: inference or missing consumer evidence |
|
||||
| Behavioral risk | Sync-critical: convergence/data loss/security/format/transaction risk; high: broad lifecycle or compatibility impact; medium: bounded behavior surface; low: no runtime contract change |
|
||||
| Validation cost | Small: focused unit/static checks; medium: subsystem integration or provider matrix; large: multi-client/provider/PostgreSQL/migration/soak evidence |
|
||||
|
||||
Unknown evidence blocks admission. Rank verified candidates first by lower
|
||||
behavioral risk, then higher maintenance benefit, stronger evidence, lower
|
||||
validation cost, and greater reversibility. Estimated production LOC is a
|
||||
secondary tie-breaker only; test and safety coverage are never counted as
|
||||
negative benefit merely because they add lines.
|
||||
|
||||
### Wave D exit criteria
|
||||
|
||||
- Every proposed record has one terminal triage state or an immutable
|
||||
verification-ready revision.
|
||||
- Duplicate keys, prior plans, and existing issues are linked before admission.
|
||||
- Each admitted candidate has explicit invariants, consumer/format checks, a
|
||||
behavioral-equivalence claim, and commands a verifier can reproduce.
|
||||
|
||||
## Wave E: fresh-context verification
|
||||
|
||||
Assign exactly one verification-ready candidate revision to each fresh-context
|
||||
reviewer. A verifier must be a new session that held no discovery, triage,
|
||||
coordination, or earlier verification role in the audit. Every required
|
||||
reviewer receives the same immutable hashed candidate packet without verifier
|
||||
conclusions; their reports remain separate and hidden from one another until
|
||||
all required reviews finish.
|
||||
|
||||
The eight seed runs are only initial capacity; create another run within the
|
||||
frozen budget for every admitted candidate above eight. A sync-critical
|
||||
candidate receives two reviewers. If fewer than eight candidates pass triage,
|
||||
unused seed runs challenge the highest-risk retained or decision-required
|
||||
records as negative controls; they cannot promote those records without
|
||||
returning them through triage.
|
||||
|
||||
Each verifier must independently reopen the cited files at the matching
|
||||
baseline, repeat the evidence commands, inspect dynamic/DI/serialized/plugin and
|
||||
old-client consumers where applicable, challenge the test map, and try to
|
||||
disprove behavioral equivalence. A report based only on the candidate author’s
|
||||
summary does not count.
|
||||
|
||||
Classify each challenge as contract misread, valid/actionable, valid trade-off,
|
||||
or noise. The coordinator revises, rejects, or marks the candidate
|
||||
decision-required rather than averaging opinions. A material revision returns
|
||||
to `verification-ready`; a cleanly reproduced candidate becomes `verified`.
|
||||
Sync-critical candidates additionally require explicit maintainer approval in a
|
||||
future implementation-planning turn.
|
||||
|
||||
### Wave E exit criteria
|
||||
|
||||
- Every admitted revision has an independent report tied to its baseline and
|
||||
revision hash; every sync-critical revision has two.
|
||||
- Every material evidence command is reproduced. A failure blocks verification
|
||||
unless the verifier independently reproduces equivalent evidence and records
|
||||
why it is equivalent; non-material failures are recorded.
|
||||
- No unresolved valid/actionable challenge is labeled `verified`.
|
||||
|
||||
## Wave F: final synthesis
|
||||
|
||||
| ID | Responsibility |
|
||||
| --- | --- |
|
||||
| F1 | Build a dependency graph from verified candidates and all file, invariant, persisted-format, public-contract, test-harness, and transitive-consumer overlaps |
|
||||
| F2 | Fresh completeness challenge against the A1 manifest, then return accepted, rejected, retained, already-tracked, and decision-required summaries |
|
||||
|
||||
F1 and F2 are the bounded lead aggregators for any manifest-derived slice runs
|
||||
and return reports. The coordinator is the only final editor and applies them
|
||||
sequentially after all Wave E reports are reconciled. If the frozen F budget
|
||||
cannot cover the complete manifest and ledger, the audit stops rather than
|
||||
claiming completeness.
|
||||
|
||||
### Wave F exit criteria
|
||||
|
||||
- Every A1 manifest entry maps to an audit report and every report maps to a
|
||||
terminal finding state.
|
||||
- Every verified candidate maps to its independent verification evidence and a
|
||||
dependency-graph node.
|
||||
- Any coverage, evidence, compatibility, or maintainer decision gap is explicit
|
||||
rather than silently omitted from the roadmap.
|
||||
|
||||
### Required final outputs
|
||||
|
||||
1. Exact scope manifest and reproducible baseline.
|
||||
2. Invariant-to-code-to-test traceability matrix.
|
||||
3. Dependency and state-machine ownership map.
|
||||
4. Verified candidate register with evidence and classification bands.
|
||||
5. Retain/rejected-hypothesis register, so future audits do not repeat unsafe
|
||||
suggestions.
|
||||
6. Compatibility/migration retirement ledger with human decision points.
|
||||
7. Scenario-to-test matrix and verification commands.
|
||||
8. Small, dependency-ordered implementation roadmap.
|
||||
9. Documentation corrections separated from behavior changes.
|
||||
|
||||
All outputs remain local. Reading or changing GitHub issues, dispatching CI,
|
||||
committing, pushing, opening a PR, or publishing results requires explicit
|
||||
authorization for that exact action.
|
||||
|
||||
## Verification ladder for eventual implementation
|
||||
|
||||
The audit itself is read-only apart from its coordinator-owned local research
|
||||
artifacts. The following section is reference material, not permission to
|
||||
implement. Source/test/config/doc edits and external actions require a separate
|
||||
user request. For every later-approved implementation candidate:
|
||||
|
||||
1. Freeze the behavior with focused characterization tests before refactoring.
|
||||
2. Make one behavior-preserving simplification at a time; do not combine it
|
||||
with a feature or protocol change.
|
||||
3. Run `npm run checkFile <filepath>` for every modified `.ts` or `.scss` file.
|
||||
4. Run the narrow affected unit/package/contract tests.
|
||||
5. Run the applicable subsystem integration tests:
|
||||
capture → persist → hydrate → replay, remote apply, compaction, migration,
|
||||
import, conflict, repair, encryption, or adapter parity.
|
||||
6. For shared boundaries, verify client/server HTTP contracts, shared-schema
|
||||
compatibility, IndexedDB/SQLite parity, and timezone behavior where relevant.
|
||||
7. Run the smallest relevant E2E with `--retries=0`, including two-client
|
||||
convergence and both provider families when shared code changes.
|
||||
8. For server/storage changes, run the real-PostgreSQL integration suites.
|
||||
9. For sync-critical work, after explicit authorization, manually dispatch the
|
||||
scheduled SuperSync and WebDAV suites for the branch and run the relevant
|
||||
failure/soak scenarios.
|
||||
10. Re-review the final diff; behavior tests should normally remain unchanged,
|
||||
and production code plus its safety coverage must not be deleted together.
|
||||
|
||||
## Implementation ordering after the audit
|
||||
|
||||
Audit high-risk areas early, but implement in this order:
|
||||
|
||||
1. Verified dead declarations, deprecated aliases after call-site migration,
|
||||
no-value wrappers, stale docs, and test-harness cleanup.
|
||||
2. Pure duplicated helpers and narrow result/type simplifications.
|
||||
3. Provider-local duplication with no wire-format or credential behavior change.
|
||||
4. Orchestration ownership and result-state simplification, one service seam at
|
||||
a time.
|
||||
5. Persistence/backend migration cleanup after rollout preconditions are met.
|
||||
6. Conflict, vector-clock, encryption, full-state, schema, and server transaction
|
||||
changes only with their dedicated plans and safety gates.
|
||||
|
||||
Keep implementation candidates to one reviewable behavior-preserving purpose,
|
||||
normally no more than five production files. F1 may recommend parallel coding
|
||||
only when no known overlap exists in files, protected invariants, public or
|
||||
persisted contracts, wire formats, schemas, migrations, tests/fixtures/harnesses,
|
||||
or transitive consumers. Parallel work uses isolated branches/worktrees; it is
|
||||
integrated sequentially, with affected contract, convergence, migration, and
|
||||
recovery tests rerun on each combined state before the next candidate is
|
||||
integrated. Any known overlap serializes even the coding. This rule includes,
|
||||
but is not limited to, vector clocks versus server conflict logic, uploads
|
||||
versus Prisma indexes, full-state versus snapshots, encryption formats versus
|
||||
guards, shared HTTP contracts versus validators, file envelopes versus
|
||||
provider CAS, and production behavior versus the tests that prove it.
|
||||
|
||||
## Audit completion measures
|
||||
|
||||
- 100% of the scope manifest has a primary owner and an audit result.
|
||||
- 100% of verified candidates cite the baseline, code, callers/registrations,
|
||||
relevant formats, history, invariants, tests, evidence commands, and verifier.
|
||||
- Every admitted finding has an independent verifier; sync-critical findings
|
||||
have two, and unresolved items have explicit states.
|
||||
- Every manifest entry and candidate revision is traceable through the ledger;
|
||||
the totals reconcile without orphaned or duplicate records.
|
||||
- No candidate is admitted because of LOC or file size alone.
|
||||
- F2 records coverage gaps and retained complexity, so the audit does not claim
|
||||
completeness by silently excluding difficult areas.
|
||||
|
||||
## Later implementation outcome measures
|
||||
|
||||
These measures apply only after separately authorized implementations:
|
||||
|
||||
- Replay determinism, multi-client convergence, provider parity, recovery,
|
||||
migration, privacy, and encryption coverage do not decrease.
|
||||
- Dependency edges/cycles, public exports, duplicated policy locations, flag
|
||||
combinations, and state-machine ownership decrease where proven useful.
|
||||
- Fixed waits, E2E flake rate, and CI runtime/cost improve without losing
|
||||
distinct scenarios.
|
||||
- Documentation claims link to current code/tests and stale duplications are
|
||||
removed.
|
||||
- Maintained production LOC decreases across completed candidates when that is
|
||||
the clearest solution; neutral or increased LOC is acceptable when safety and
|
||||
comprehension measurably improve.
|
||||
|
||||
## Stop conditions
|
||||
|
||||
Stop and request a maintainer decision when:
|
||||
|
||||
- deleting code requires ending support for a backup, schema, provider, or wire
|
||||
format;
|
||||
- a candidate changes conflict, import, repair, delete-wins, encryption, or
|
||||
transaction semantics rather than preserving behavior;
|
||||
- existing or feasible characterization tests cannot describe the protected
|
||||
behavior, or a representative mutation would not make them fail;
|
||||
- the simpler design adds a new public API/package without a demonstrated user;
|
||||
- three adversarial passes still find substantive unresolved risks; or
|
||||
- the total maintenance and comprehension benefit is small relative to
|
||||
migration and verification cost, regardless of the LOC estimate.
|
||||
251
docs/research/sync-simplification-audit/baseline.md
Normal file
251
docs/research/sync-simplification-audit/baseline.md
Normal file
|
|
@ -0,0 +1,251 @@
|
|||
# Sync simplification audit baseline
|
||||
|
||||
Status: frozen and independently reproduced by A1R3; Wave A complete,
|
||||
including the authorized read-only external issue reconciliation
|
||||
Date: 2026-07-16
|
||||
Baseline ID: `9b4481332dd635dce29da3774d1b8601ea213467f07dfc7fb0417f36328c3135`
|
||||
|
||||
## Repository fingerprint
|
||||
|
||||
| Field | Value |
|
||||
| --- | --- |
|
||||
| Commit | `104043e2d220336d37c96623229640233093f045` |
|
||||
| In-scope status | `?? docs/plans/2026-07-16-sync-simplification-audit.md` |
|
||||
| Tracked diff SHA-256 | `e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855` |
|
||||
| In-scope untracked file | `docs/plans/2026-07-16-sync-simplification-audit.md` |
|
||||
| Untracked file SHA-256 | `bbed7c26e71036abab0bbe984f99669094a0731eb3fb47b512e833176f3a9393` |
|
||||
| Scope records | 1,442 |
|
||||
| Scope-manifest SHA-256 | `7d38cfa9f7a06d9f4da3be822c715ee01e418956a71251798cede66fbb1144bb` |
|
||||
|
||||
The tracked diff hash is from:
|
||||
|
||||
```sh
|
||||
git diff --binary --full-index --no-ext-diff HEAD -- . | sha256sum
|
||||
```
|
||||
|
||||
The only drift exclusion is `docs/research/sync-simplification-audit/**`.
|
||||
It did not exist when the repository fingerprint was captured and contains only
|
||||
the five coordinator-owned audit artifacts. Source, tests, configuration,
|
||||
existing documentation, the plan, Git state, services, and external systems are
|
||||
not excluded.
|
||||
|
||||
The baseline ID is SHA-256 over these bytes:
|
||||
|
||||
```text
|
||||
"A1-v1" NUL
|
||||
commit NUL
|
||||
exact porcelain-v1-uall bytes NUL
|
||||
tracked-diff SHA-256 NUL
|
||||
sorted("path" NUL "sha256" LF) for each in-scope untracked file NUL
|
||||
scope-manifest SHA-256
|
||||
```
|
||||
|
||||
## Manifest construction
|
||||
|
||||
The canonical universe is `git ls-files -co --exclude-standard -z`. Paths are
|
||||
UTF-8, bytewise sorted, and hashed as `path + LF`, including the final LF.
|
||||
The exact merged path list is the first column of
|
||||
[`ownership.tsv`](ownership.tsv).
|
||||
|
||||
The direct seed and closure were split because the 845-file lower bound could
|
||||
not fit one 60-file inspection assignment:
|
||||
|
||||
| Slice | Scope | Files | Path-list SHA-256 | Physical LOC |
|
||||
| --- | --- | ---: | --- | ---: |
|
||||
| A1-M1 | Four sync/server packages plus app op-log and sync shell | 733 | `e9b8d804d681f0776e935c8a7b940af60a185cf5e1189970303f99306299a1f0` | 249,112 |
|
||||
| A1-M2 | App/root-store/platform import, registration, action, provider, and serialized-string closure | 512 | `e42c80ba1236ff56c18ea27b88bf9b746e5bdc3a8fee514239fb05f25b29ab82` | 167,311 |
|
||||
| A1-M3 | Sync E2E closure, canonical docs, lint, CI, and root build/runtime selection | 197 | `d72096920baf37492990e82bcec994f1089d9069d930c99e43b8bf1b077501a2` | 64,572 |
|
||||
| **Merged** | Deduplicated union | **1,442** | **`7d38cfa9f7a06d9f4da3be822c715ee01e418956a71251798cede66fbb1144bb`** | **480,995** |
|
||||
|
||||
The sole LOC-target exclusion is the tracked vendored/minified
|
||||
`packages/super-sync-server/public/simplewebauthn-browser.min.js` (363
|
||||
physical lines). It remains in the manifest and retain inventory. Immutable SQL
|
||||
migrations, snapshots, compatibility code, auth/account perimeter code, and
|
||||
operational material remain in the denominator; later auditors may classify
|
||||
them retained but may not silently remove them.
|
||||
|
||||
### A1-M1 exact seed procedure
|
||||
|
||||
```sh
|
||||
git ls-files -co --exclude-standard -- \
|
||||
packages/sync-core \
|
||||
packages/sync-providers \
|
||||
packages/shared-schema \
|
||||
packages/super-sync-server \
|
||||
src/app/op-log \
|
||||
src/app/imex/sync |
|
||||
LC_ALL=C sort
|
||||
```
|
||||
|
||||
| Surface | Production TS files / LOC | Test TS files / LOC | Docs files / LOC | Other files / LOC |
|
||||
| --- | ---: | ---: | ---: | ---: |
|
||||
| `packages/sync-core` | 28 / 3,954 | 12 / 4,675 | 1 / 73 | 5 / 83 |
|
||||
| `packages/sync-providers` | 50 / 7,249 | 22 / 6,798 | 0 / 0 | 5 / 208 |
|
||||
| `packages/shared-schema` | 12 / 1,054 | 5 / 1,136 | 0 / 0 | 3 / 59 |
|
||||
| `packages/super-sync-server` | 50 / 14,812 | 60 / 31,159 | 16 / 5,597 | 78 / 7,321 |
|
||||
| `src/app/op-log` | 145 / 42,639 | 164 / 102,636 | 0 / 0 | 6 / 477 |
|
||||
| `src/app/imex/sync` | 31 / 6,968 | 21 / 10,600 | 0 / 0 | 19 / 1,614 |
|
||||
| **Total** | **316 / 76,676** | **284 / 157,004** | **17 / 5,670** | **116 / 9,762** |
|
||||
|
||||
A TypeScript AST pass found 134 external incoming files, 149 external outgoing
|
||||
targets, and a 251-file union. Its path-set hash was
|
||||
`0ed16ed1115d5cf3465563f207839aae224f37b486ccbe6d6f5f2ae8be72662d`.
|
||||
All relative imports resolved.
|
||||
|
||||
### A1-M2 closure rules
|
||||
|
||||
The executable repair recipe was independently challenged after two validators
|
||||
got 218 primary matches instead of 222. The difference was four tracked legacy
|
||||
PFAPI JavaScript files hidden by `.gitignore:76` (`src/app/**/*.js`) from
|
||||
default positional `rg`. The repaired recipe reads the Git universe directly,
|
||||
which correctly retains them without admitting arbitrary ignored output.
|
||||
|
||||
The closure includes:
|
||||
|
||||
- all `src/app/root-store/meta/**`;
|
||||
- primary exact sync/package/action/provider/vector-clock terms;
|
||||
- both directions of imports between M1 and M2, with M1-to-M2 domain targets
|
||||
terminal unless independently admitted;
|
||||
- byte-delimited sync/op-log/vector-clock/provider path families;
|
||||
- unambiguous operation-log, clean-slate, file-sync, and WebSocket evidence;
|
||||
- replay/hydration/SYNC-SAFE evidence in effects and matching specs;
|
||||
- explicit route, logical-day, Android, Electron, and iOS registration or
|
||||
serialized bridge boundaries;
|
||||
- same-stem tests and Angular resources for active files.
|
||||
|
||||
Intermediate reproduced sets:
|
||||
|
||||
| Set | Count | SHA-256 |
|
||||
| --- | ---: | --- |
|
||||
| M2 universe | 2,322 | `2cec1ab3a0dab2d0786d4dfde565fcb045e96adf80d0ac923bf70d58d16e3162` |
|
||||
| Root-meta seed | 46 | `3383e395fd8028b0df3f75769d2fbef861c2f816facbb86dc12b8651a4fb8511` |
|
||||
| Primary | 222 | `050cedb0ec5afd33f3c81d9f65bdbe51ca29eebdc08a1df8eac6d41f90f3193c` |
|
||||
| Import union | 247 | `7b08072fa222a41e564d2495023ad08beef0644b5f6da4e6a93153fad7a17735` |
|
||||
| Path admissions | 44 | `760ee810cdd8fe948999e43b1fa981e8854a7f6d7d8de2873d47948a0ac498ac` |
|
||||
| Supplemental admissions | 38 | `a0785c8f7e55be4b30eccc1afe856732a3402459b2694c452044a460f0aefceb` |
|
||||
| Explicit boundary edges | 50 | `5ee9be15ef26ef5b35896399f77dd9336c0842f22ec46ec20e9a0f692af93e7b` |
|
||||
| Companions/resources | 136 | `b4eb5ca7fb0364a1a0d0476abbd116a62f1fc1721ba0255146b590686c716552` |
|
||||
| Excluded supplemental noise | 97 | `f06cb8f44bc8ff893b3663ba923fd24112bbf9d986ca404e61dc75a0e4d78293` |
|
||||
|
||||
The nine validation slices, A1R, and A1R2 found 58 closure omissions in total: build and
|
||||
frontend registrations, direct consumers/sidecars, serialized-shape and
|
||||
logical-day dependencies, Angular resources, and existing proving tests.
|
||||
Revisions 2–6 added their complete source/test/resource closure. They also
|
||||
removed seven independently reproduced lexical false positives: one
|
||||
locale-only spec, three non-sync plugin OAuth bridge/storage files, two
|
||||
idle-only break-service files, and one local-only plugin secret store. M2 now
|
||||
contains 331 production/source files (75,857 LOC), 178 test files (91,192 LOC),
|
||||
and three config/platform metadata files (262 LOC). The original executable
|
||||
recipe and its intermediate hashes describe the pre-validation candidate set;
|
||||
the authoritative revised manifest is the exact first column of
|
||||
`ownership.tsv`. A1R must independently reproduce the closure amendments and
|
||||
challenge them rather than trust this summary.
|
||||
|
||||
### A1-M3 exact composition
|
||||
|
||||
- 90 top-level `e2e/tests/sync/*.spec.ts` files and 255 executable static
|
||||
tests: 253 `test(...)` declarations plus two aliased `base(...)` tests in
|
||||
`import-sync.spec.ts`;
|
||||
- 34 transitive E2E fixture/page/helper/config files;
|
||||
- all 22 `docs/sync-and-op-log/**` files and 16 explicit ADR/plan/E2E docs;
|
||||
- all 11 `eslint-local-rules/**` files plus `eslint.config.js`;
|
||||
- seven CI/action files and 16 root build/runtime selection files.
|
||||
|
||||
| Category | Files | Physical LOC |
|
||||
| --- | ---: | ---: |
|
||||
| Sync E2E specs | 90 | 33,047 |
|
||||
| E2E harness/config | 34 | 10,475 |
|
||||
| Documentation/ADR/plans | 38 | 16,199 |
|
||||
| Sync lint rules/config | 12 | 1,992 |
|
||||
| CI/workflow selection | 7 | 1,528 |
|
||||
| Scripts/root build config | 16 | 1,331 |
|
||||
|
||||
## Query lexicon and closure
|
||||
|
||||
Primary expression:
|
||||
|
||||
```regex
|
||||
(@sp/sync-(core|providers)|@sp/shared-schema|src/app/op-log|/op-log/|SuperSync|SUPER_SYNC|super-sync|supersync|WebDAV|WEBDAV|webdav|SyncProvider|SYNC_PROVIDER|syncProvider|sync-config|syncConfig|PersistentAction|persistentAction|PERSISTENT_ACTION|LOCAL_ACTIONS|ALL_ACTIONS|skipDuringSyncWindow|OperationLog|operationLog|operation-log|op-log|VectorClock|vectorClock|vector-clock|SYNC_IMPORT|BACKUP_IMPORT)
|
||||
```
|
||||
|
||||
Supplemental expression:
|
||||
|
||||
```regex
|
||||
(?i)(operation log|replay|hydration|clean[-_ ]slate|file[-_ ]based[-_ ]sync|nextcloud|dropbox|onedrive|snapshot|conflict|repair|quota|websocket)
|
||||
```
|
||||
|
||||
Closure follows static exports/imports, literal dynamic imports/require calls,
|
||||
package aliases/barrels/build entries, DI/effect/token/meta/entity/provider
|
||||
registrations, exact serialized action/entity/provider/schema/full-state/wire
|
||||
strings, co-located tests and Angular resources, and the sync E2E import graph.
|
||||
Generic registered domain files are terminal perimeter unless another exact edge
|
||||
admits them. Name-only false positives such as RxJS replay, UI snapshots,
|
||||
calendar/issue-provider sync, release metadata, plugin-dev `sync-md`, and
|
||||
unreferenced platform assets require an independent edge.
|
||||
|
||||
## Frozen continuation ceilings
|
||||
|
||||
Because the final manifest exceeds 900 paths:
|
||||
|
||||
- Wave A continuation ceiling: **26 runs** (raised from 25 by explicit user
|
||||
approval after A1R2 found five same-stem test omissions).
|
||||
- Waves B and C combined ceiling: **78 runs**, including their 46 seed runs and
|
||||
manifest-derived continuation capacity.
|
||||
|
||||
Exceeding either ceiling requires explicit user approval. D1, D2-D4, Wave E,
|
||||
and Wave F capacities are frozen only at their prescribed later phase gates.
|
||||
|
||||
## Primary-domain ownership
|
||||
|
||||
A3 assigned all 1,442 manifest paths by deterministic first-match rules. The
|
||||
complete path-level assignment is `ownership.tsv`; counts reconcile with zero
|
||||
unmatched paths:
|
||||
|
||||
```text
|
||||
B01 32 B02 8 B03 8 B04 21 B05 8 B06 6 B07 9 B08 12
|
||||
B09 9 B10 28 B11 18 B12 15 B13 13 B14 20 B15 2 B16 8
|
||||
B17 6 B18 9 B19 24 B20 5 B21 9 B22 50 B23 26 B24 14
|
||||
B25 25 B26 9 B27 20 B28 16 B29 48 B30 30 B31 22 B32 15
|
||||
B33 17 B34 85 B35 481 B36 185 B37 45 B38 84
|
||||
```
|
||||
|
||||
The largest owners require stable child slices in Wave B: B34 server
|
||||
lifecycle/auth, B35 app/platform perimeter, B36 test topology, and B38
|
||||
database/operations. Test paths remain B36 primary and cross-link to their
|
||||
behavior owner; provider package paths remain provider-domain primary and
|
||||
cross-link to B30 shared infrastructure.
|
||||
|
||||
## Dependency and API map (A3)
|
||||
|
||||
A TypeScript AST pass covered 1,204 code files and 6,484 resolved
|
||||
manifest-internal edges.
|
||||
|
||||
- Cross-surface directions: app→shared-schema 9, app→sync-core 55,
|
||||
app→sync-providers 55, providers→sync-core 27, server→shared-schema 15,
|
||||
server→sync-core 2.
|
||||
- No forbidden sync-core/shared-schema direction or non-public `@sp/*`
|
||||
specifier was found. Provider package exports and tsconfig aliases both expose
|
||||
the same 13 focused subpaths.
|
||||
- Public surface counts: sync-core root 101 named re-exports; shared-schema 62;
|
||||
provider subpaths 117 visible declarations; app `sync-exports.ts` 44
|
||||
re-exports used by 19 manifest consumers.
|
||||
- Five strongly connected components remain: Dropbox↔DropboxApi;
|
||||
archive-model↔time-tracking-model; a 19-node reducer/model/load registry; a
|
||||
21-node app sync/config/encryption/orchestration component; and
|
||||
plugin-service↔plugin-bridge.
|
||||
- High fan-in: operation types 177, op-log store 97, sync-core index 90,
|
||||
provider constants 68, operation-log constants 57, `LOCAL_ACTIONS` 53,
|
||||
lock service 51. High fan-out: feature-store registration 61,
|
||||
operation-log-sync 43, sync wrapper 39, conflict resolution 35, entity/model
|
||||
registries 30 each.
|
||||
- Registries: 21 shared entity strings (18 configured state entities plus
|
||||
ALL/MIGRATION/RECOVERY), 17 ordered meta-reducers, centralized feature-effect
|
||||
registration, and four unconditional plus three platform-conditional
|
||||
providers.
|
||||
|
||||
A3 routing signals: the server recovery script deep-imports sync-core source
|
||||
despite a public decrypt export; Dropbox is the only provider-package SCC; the
|
||||
large app SCC warrants seam-by-seam review but not package extraction;
|
||||
Electron/app imports cross in both directions and need IPC compatibility
|
||||
review; and app `sync-exports.ts` is a second compatibility surface whose
|
||||
consumers/deprecated aliases should be audited before widening it.
|
||||
8065
docs/research/sync-simplification-audit/findings.md
Normal file
8065
docs/research/sync-simplification-audit/findings.md
Normal file
File diff suppressed because it is too large
Load diff
1443
docs/research/sync-simplification-audit/ownership.tsv
Normal file
1443
docs/research/sync-simplification-audit/ownership.tsv
Normal file
File diff suppressed because it is too large
Load diff
|
|
@ -0,0 +1,317 @@
|
|||
# Provisional sync simplification risk/reward backlog
|
||||
|
||||
- Status: post-audit derived triage; all entries remain unverified
|
||||
- Date: 2026-07-17
|
||||
- Source audit snapshot: baseline `5d02ec86…2651`, findings
|
||||
`83acd393…c8e9`, retained `ac42fde4…e4d`, verification
|
||||
`9dda34db…f18d`
|
||||
- Authoritative verified queue:
|
||||
[verified-risk-reward.md](verified-risk-reward.md)
|
||||
|
||||
This document applies a readiness-adjusted risk/reward ordering to 25 groups
|
||||
nominated from the 204 stable groups that did not enter the terminal Wave E
|
||||
register. It is derived from [findings.md](findings.md),
|
||||
[verification.md](verification.md), and [retained.md](retained.md). It does not
|
||||
rank the complete 204-group universe, modify the frozen audit, verify a
|
||||
candidate, authorize implementation, or claim exhaustive cross-cutting
|
||||
verification.
|
||||
|
||||
## Reconciled universe
|
||||
|
||||
| Disposition at the end of the audit | Stable groups | Treatment here |
|
||||
| ----------------------------------- | ------------: | --------------------------------------------- |
|
||||
| Verified | 5 | Kept only in the authoritative verified queue |
|
||||
| Rejected | 1 | Excluded |
|
||||
| Decision-required after Wave E | 2 | Excluded |
|
||||
| Discovered/proposed, unverified | 204 | 25 nominated and ranked; 179 remain unranked |
|
||||
| **Total** | **212** | D1-normalized stable groups |
|
||||
|
||||
The 204 eligible groups were screened in three disjoint stable-ID ranges:
|
||||
66 groups in `SSA-0001`–`SSA-0070`, 70 in `SSA-0071`–`SSA-0140`, and 68 in
|
||||
`SSA-0141`–`SSA-0212`. Those passes nominated 25 candidates but did not assign
|
||||
the same four bands to every omitted group or prove that no omitted candidate
|
||||
could outrank the cutline. This was packet-level screening only. Source
|
||||
consumers, history, tests, and revision hashes were not freshly re-verified.
|
||||
|
||||
## Ordering method
|
||||
|
||||
Within the nominated shortlist, the ranking uses only fields already recorded
|
||||
in each immutable origin packet:
|
||||
|
||||
1. User-data protection, data-integrity protection, or removal of false test
|
||||
and architecture confidence.
|
||||
2. Maintenance payoff, including bounded production/test deletion and removal
|
||||
of misleading contracts.
|
||||
3. Stated behavioral risk, reversibility, and evidence confidence.
|
||||
4. Required validation breadth, reviewer count, compatibility gates, and
|
||||
dependencies.
|
||||
5. The fast-track D2–D4 non-admission register and retained-mechanism rules.
|
||||
|
||||
No synthetic numeric score was created. `Reproduced` and `supported` below are
|
||||
the origin packet's evidence labels, not fresh verifier verdicts. Ranks are
|
||||
readiness-adjusted: a high-value item with an unresolved decision or broad
|
||||
validation gate can appear below a smaller but well-bounded candidate.
|
||||
|
||||
## Provisional ranked shortlist (25)
|
||||
|
||||
### Tier A — recommended next verification wave
|
||||
|
||||
These eight have the best current combination of user, test-integrity,
|
||||
documentation, or maintenance value, bounded scope, reversibility, and
|
||||
evidence. Their order is a verification priority, not an implementation
|
||||
dependency graph.
|
||||
|
||||
| Rank | Candidate | Expected reward | Packet risk / evidence | Verification burden |
|
||||
| ---: | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ | -------------------------------------- | ----------------------------------------------------------------------------------- |
|
||||
| 1 | `SSA-0045` / B12-C03 — Stop exporting full task objects from repair diagnostics | High privacy value; closes three exportable user-content paths | Low behavioral risk; reproduced | Medium; sentinel export tests, repair/log suites, two privacy/sync reviewers |
|
||||
| 2 | `SSA-0173` / B35-C20 — Make owner-local task and reminder diagnostics privacy-safe | High privacy value; removes five title/task/repeat payload logs | Low behavioral risk; reproduced | Medium; three owners, focused effects suites, sentinel, privacy/domain reviewer |
|
||||
| 3 | `SSA-0190` / B35-C37 — Remove generic values from exportable utility logs | High preventive privacy value; removes a generic future-content footgun | Low behavioral risk; supported | Small–medium; sentinel/date/sync-window suites and privacy/sync reviewer |
|
||||
| 4 | `SSA-0151` / B36-C01 — Delete the orphaned encryption E2E failure memo | High documentation value; removes 525 stale, misleading lines | Negligible runtime risk; reproduced | Small; closure, Markdown/link checks, and fresh test-doc reviewer |
|
||||
| 5 | `SSA-0068` / B16-C01 — Make the immediate-upload debounce failure test deterministic | High test-integrity value; replaces unreachable timing coverage | Low risk; reproduced | Small; one spec, fake time, mutation checks, and timing-test reviewer |
|
||||
| 6 | `SSA-0026` / B09-C01 — Remove the unused compact log-entry codec half | High maintenance value; about 160–180 source/test LOC and a false persisted-format model removed | Low, format-sensitive risk; reproduced | Medium; closure and codec/storage suites; origin assigns no reviewer count |
|
||||
| 7 | `SSA-0136` / B34-C02 — Finish the dead DeviceService cleanup | High maintenance value; about 160–200 source/test LOC removed | Low runtime risk; reproduced | Medium; device/upload/sync suites, build/typecheck, device-lifecycle reviewer |
|
||||
| 8 | `SSA-0135` / B34-C01 — Delete the obsolete standalone decompression helper | High maintenance value; about 140–170 source/test LOC removed | Low risk; reproduced | Medium; parser assertion inventory, compressed-route suites, server-boundary review |
|
||||
|
||||
### Tier B — strong reserves
|
||||
|
||||
These are promising, but their validation surface, security sensitivity, or
|
||||
sync/test ownership is broader than Tier A.
|
||||
|
||||
| Rank | Candidate | Expected reward | Packet risk / evidence | Main gate |
|
||||
| ---: | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------- |
|
||||
| 9 | `SSA-0092` / B23-C04 — Allowlist provider-host diagnostic metadata | High privacy value and a simpler fixed allowlist | Medium security-sensitive risk; reproduced | Sentinels, two privacy/provider reviewers, and serialization with B23-C03 |
|
||||
| 10 | `SSA-0072` / B16-C05 — Keep raw upload errors out of exportable logs | High privacy value across active upload paths | Medium privacy-sensitive risk; reproduced | Upload/immediate-upload/error-meta suites and two privacy/provider reviewers |
|
||||
| 11 | `SSA-0120` / B28-C03 — Sanitize WebSocket errors before exportable logging | High privacy value across close/reconnect/error paths | Medium privacy-critical risk; reproduced | Three-service canaries, both export forms, and two privacy/sync reviewers |
|
||||
| 12 | `SSA-0139` / B33-C01 — Delete the unreachable cached-snapshot read and invalidation path | High maintenance value; about 120 source/test LOC and a false recovery path removed | Low behavioral risk; reproduced | Closure, snapshot suites, build/typecheck, and fresh server/C1 reviewer |
|
||||
| 13 | `SSA-0002` / B05-C01 — Retire the superseded duplicate-ingestion APIs | High maintenance value; about 190–270 source/test/doc LOC and a known-racy alternative model removed | Medium test-helper risk; reproduced | Broad store/recovery/remote-apply/conflict/sync proof; origin assigns no reviewer count |
|
||||
| 14 | `SSA-0066` / B15-C04 — Delete the weaker duplicate gap-key refresh test | Medium test-maintenance value; about 55 test LOC removed | Low risk; reproduced | Assertion-set diff, focused mutations, and fresh encryption-test reviewer |
|
||||
| 15 | `SSA-0030` / B08-C01 — Remove the dead remote-rehydration facade chain | Medium-high maintenance value; about 65–95 source/test LOC removed | Low risk; reproduced | Startup/hydrator/retry/wrapper closure; origin assigns no reviewer count |
|
||||
| 16 | `SSA-0058` / B13-C01 — Delete orphaned PFAPI constants and legacy-only type aliases | High maintenance value; about 90–105 production LOC removed | Low risk after export closure; reproduced | PFAPI compatibility coordination, package/build checks, and contract reviewer |
|
||||
| 17 | `SSA-0155` / B36-C05 — Delete page-object APIs left by obsolete encryption tests | High test-maintenance value; about 245–255 test LOC removed | Low runtime risk; reproduced | Closure, password scenarios, scheduled encrypted SuperSync, encryption-E2E reviewer |
|
||||
| 18 | `SSA-0142` / B33-C04 — Make the PostgreSQL vector-clock test execute production SQL | High data-integrity/test-truth value | No runtime risk; medium validation cost; reproduced | Real PostgreSQL integration, query mutations, and B33/B36 reviewer |
|
||||
| 19 | `SSA-0047` / B12-C05 — Consolidate the #7330 diagnostic validator harness | High test-maintenance value; about 170–230 test LOC removed | Low implementation risk; reproduced | Assertion map, canonical/ValidateState/replay suites, two validation/sync reviewers |
|
||||
| 20 | `SSA-0034` / B08-C05 — Collapse superseded local-only hydration test permutations | High test-maintenance value; about 180–240 test LOC removed | Low risk; reproduced | Per-key mutation map across operation/snapshot/dispatch; origin assigns no reviewer count |
|
||||
|
||||
### Tier C — high payoff, gated
|
||||
|
||||
These remain visible because their potential payoff is substantial. Any
|
||||
source-recorded admission prerequisite must be resolved before admission;
|
||||
verification requirements run only inside a separately authorized wave. No
|
||||
gate may be resolved through unrecorded verification outside a new amendment.
|
||||
|
||||
| Rank | Candidate | Expected reward | Packet risk / evidence | Gate type and requirement |
|
||||
| ---: | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 21 | `SSA-0209` / B36-C18 — Delete the legacy archive suite that only echoes its fixture | High test-maintenance value; 445 test LOC and false coverage removed | Low–medium coverage risk; reproduced | Verification: import/export E2E; archive service, reducer, and data-repair suites; parent/subtask assertions; reviewer |
|
||||
| 22 | `SSA-0102` / B30-C04 — Table-drive provider retry-classifier specifications | Medium-high test-maintenance value; about 120–180 test LOC removed | Low risk; reproduced | Verification: exact case/name/literal inventory, focused package specs/typecheck, test-quality reviewer |
|
||||
| 23 | `SSA-0141` / B33-C03 — Consolidate snapshot fast-forward tests into active owners | Very high maintenance value; about 900–1,100 test/config LOC removed | No runtime risk; medium validation cost; reproduced | Verification: machine-readable scenario matrix, causal mutations, active service/route and normal package tests, B33/B36 reviewer |
|
||||
| 24 | `SSA-0143` / B35-C01 — Replace the unsafe Android sequence-hint roadmap with a rejection fence | High preventive data-integrity value; removes a data-loss-prone recipe | Documentation-only but sync-critical; unverified | Verification: two sync reviewers, exact-reference/link checks, and mandatory preservation of the rejection fence |
|
||||
| 25 | `SSA-0087` / B22-C01 — Delete the impossible SuperSync disable-encryption path | High maintenance/security value; about 100–130 LOC and a destructive always-failing API removed | Security/sync-critical; medium validation; reproduced | Verification: closure/guards/E2E, two encryption/workflow reviewers, and preservation of every file-based disable path |
|
||||
|
||||
## Tier A verification packets
|
||||
|
||||
### 1. SSA-0045 — Stop exporting full task objects from repair diagnostics
|
||||
|
||||
- **Revision:**
|
||||
`5ce3f82462290e2557c246139d24342aacc82d3ea0ed1d942107cc3351eabbc9`
|
||||
- **Preserve:** repair results, summary counts, ordering, replay, and wire data.
|
||||
- **Prove:** sentinel task titles cannot enter exported history; retain safe
|
||||
labels/counts/IDs and run the complete repair/log coverage.
|
||||
- **Trade-off:** diagnostic payload detail is deliberately reduced.
|
||||
|
||||
### 2. SSA-0173 — Make owner-local task and reminder diagnostics privacy-safe
|
||||
|
||||
- **Revision:**
|
||||
`23150221dbb76bb3c4ca160d0c675e3faa08aa20d1b397ba71544d904d38bccf`
|
||||
- **Preserve:** scheduling, dispatch, persistence, reminder delivery, repeat
|
||||
creation, and tag ordering.
|
||||
- **Prove:** task titles, notes, reminder titles, and repeat payloads remain
|
||||
absent from exported logs across all three owners.
|
||||
- **Trade-off:** five content-bearing debug messages disappear.
|
||||
|
||||
### 3. SSA-0190 — Remove generic values from exportable utility logs
|
||||
|
||||
- **Revision:**
|
||||
`757f9d9a748ff2f45686a1119cc0e731757b5cb14fc6e960f9fdec0bae6eebe9`
|
||||
- **Preserve:** sync-window ordering, timeout/proceed behavior, formatting, and
|
||||
fallback values.
|
||||
- **Prove:** generic values and value-bearing exceptions cannot reach exported
|
||||
logs; content-free phase/category diagnostics may remain.
|
||||
- **Trade-off:** arbitrary formatting and operator payload detail is removed.
|
||||
|
||||
### 4. SSA-0151 — Delete the orphaned encryption E2E failure memo
|
||||
|
||||
- **Revision:**
|
||||
`2e4db0e7be318d4cbf8adb6f35dab1a6f5bd480b2d25153a0bd10c8b91f3ac4e`
|
||||
- **Preserve:** current execution guidance in `e2e/CLAUDE.md`, live encryption
|
||||
scenarios, and every supported encryption contract.
|
||||
- **Prove:** backlink, path, local-storage-key, and selector closure; Markdown
|
||||
links and the final diff remain clean.
|
||||
- **Trade-off:** a 525-line obsolete failure memo disappears, leaving current
|
||||
executable owners as the authority.
|
||||
|
||||
### 5. SSA-0068 — Make the immediate-upload debounce failure test deterministic
|
||||
|
||||
- **Revision:**
|
||||
`6df55bc133102b81dddc43f69604cd8cac330b8779f0c2c9123755409c68a6dd`
|
||||
- **Preserve:** the real 2,000 ms debounce boundary, rejected-promise handling,
|
||||
queue restoration, and status restoration.
|
||||
- **Prove:** fake-time mutation checks fail when call timing or error recovery
|
||||
regresses; no wall-clock wait remains.
|
||||
- **Trade-off:** none beyond replacing a misleading test implementation.
|
||||
|
||||
### 6. SSA-0026 — Remove the unused compact log-entry codec half
|
||||
|
||||
- **Revision:**
|
||||
`219cf80e1322d1fa422d9d86ee3aa0c2681e37f37551ee183046313cb0308ae7`
|
||||
- **Preserve:** compact operation encoding, historical full-operation rows,
|
||||
lifecycle fields, IndexedDB storage, and file-sync envelopes.
|
||||
- **Prove:** no package, dynamic, persisted, wire, or production consumer uses
|
||||
the whole-entry codec before deleting it and its direct tests.
|
||||
- **Trade-off:** an unused alternative persisted-format model disappears.
|
||||
|
||||
### 7. SSA-0136 — Finish the dead DeviceService cleanup
|
||||
|
||||
- **Revision:**
|
||||
`70dbbe8fdb8ae198357b047188bfbef3b9a5785faee8808014ef58c421ed3aa1`
|
||||
- **Preserve:** live device upsert and state initialization behavior.
|
||||
- **Prove:** both target methods remain test-only after full closure; run
|
||||
device, upload, sync-service, and duplicate-precheck coverage.
|
||||
- **Trade-off:** direct tests of the dead queries are removed with them.
|
||||
|
||||
### 8. SSA-0135 — Delete the obsolete standalone decompression helper
|
||||
|
||||
- **Revision:**
|
||||
`10a6e2e7cd16885b6f753ef8bba229a0ddf4ac32753bea5e51103600cacf5e27`
|
||||
- **Preserve:** gzip parsing, request-size enforcement, invalid-input errors,
|
||||
Unicode behavior, and the live compressed request boundary.
|
||||
- **Prove:** every unique assertion is retained by the integrated parser suite
|
||||
before deleting the standalone helper and tests.
|
||||
- **Trade-off:** none if the assertion inventory closes cleanly.
|
||||
|
||||
## Exact revision registry for ranks 9–25
|
||||
|
||||
| Rank | Stable ID | Origin | Immutable revision |
|
||||
| ---: | ---------- | ------- | ------------------------------------------------------------------ |
|
||||
| 9 | `SSA-0092` | B23-C04 | `77734fe3b1b29989be623210544f8ddb7b88bd002cc59e015299677ff05fc4b2` |
|
||||
| 10 | `SSA-0072` | B16-C05 | `466640e8678c7b432f94cc5ffb95d847d734288ff16bd234a7e1e9db6c6b2075` |
|
||||
| 11 | `SSA-0120` | B28-C03 | `3aab82a0f96195288147cf8fe717ddde4952d0bce2bc9464409c665cb54bd775` |
|
||||
| 12 | `SSA-0139` | B33-C01 | `5c3f0a71881d6a711372e2a973bf891b218757bf16d66bdab68f20021b61fbc3` |
|
||||
| 13 | `SSA-0002` | B05-C01 | `a21ee57393756742748ade8d994826239756cd72b48069d904c1a94f8b7a324b` |
|
||||
| 14 | `SSA-0066` | B15-C04 | `f672d40f8a0a056bb1d24de50f996df8875644cb2fba703f56447b3e4217d673` |
|
||||
| 15 | `SSA-0030` | B08-C01 | `a360c8019486e74642c0fb45072dba3b448f211888832191f5727c8564fa6528` |
|
||||
| 16 | `SSA-0058` | B13-C01 | `df039e9b1843346331007c282396a26886943c8c44c51f6ed0fd4bf75bc4cbfc` |
|
||||
| 17 | `SSA-0155` | B36-C05 | `6fa4a8556c0704785572d231b42338cac69582a52714888493151269d4298295` |
|
||||
| 18 | `SSA-0142` | B33-C04 | `86b186bf0d756b29e6ee6b24b9c641d5f5bc70902edb8f3e248c3c787644bdd0` |
|
||||
| 19 | `SSA-0047` | B12-C05 | `f01857a7d6a305ecd82c5b538c86410a63df1d04af786978454f30929155423b` |
|
||||
| 20 | `SSA-0034` | B08-C05 | `18392a332fc8db1f618aae3ac128dd8348e1e52a71e957c2b68b76c0d6916371` |
|
||||
| 21 | `SSA-0209` | B36-C18 | `b4895172386076789b23db51354a9bc8e89bc4c056f0259c2b6dea5bfaa7ca5a` |
|
||||
| 22 | `SSA-0102` | B30-C04 | `38eac966b43dd48a255ef7883766f5312b26b17cd50d5fa8f30808ab41081684` |
|
||||
| 23 | `SSA-0141` | B33-C03 | `304d587e986b8d45e6b9b9eca27cb660cc0acee662b1e464a6c82cf7384b74cd` |
|
||||
| 24 | `SSA-0143` | B35-C01 | `be4fcefe437b1d10105885883aab2e8ca4e68666a790ea27a381ee1b671143bb` |
|
||||
| 25 | `SSA-0087` | B22-C01 | `d27e6079df3c9b422ed82b7414ed09f2ff79496b9c78c05b3685be64d6adc20f` |
|
||||
|
||||
## Reviewer and validation registry
|
||||
|
||||
This registry carries forward the origin packet's reviewer wording and the
|
||||
main source-recorded gate. “None assigned” means the origin says `none yet`; it
|
||||
does not waive fresh review. Any future amendment should assign one fresh
|
||||
domain reviewer to ranks 6, 13, 15, and 20 before admission.
|
||||
|
||||
| Rank | Origin reviewer requirement | Mandatory validation or dependency |
|
||||
| ---: | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 1 | Two fresh privacy/sync reviewers | Sentinel-title exclusion, core log export, full data-repair specs, and modified-file checks |
|
||||
| 2 | Fresh privacy/reminder/repeat reviewer | All three owners, focused reminder/tag/repeat effects, and exported-log sentinel |
|
||||
| 3 | Fresh privacy/sync reviewer | Sentinel log spies, locale-date and day-change/sync-window specs, and modified-file checks |
|
||||
| 4 | Fresh test-doc reviewer | Backlink/path/key/selector closure, Markdown-link scan, and `git diff --check` |
|
||||
| 5 | Fresh timing-test reviewer | Fake time before/at 2,000 ms, rejection handling, queue/status restoration, and modified-file check |
|
||||
| 6 | None assigned (`none yet`) | Tracked/export/dynamic closure; codec, historical-row, file-adapter, and compact-operation suites |
|
||||
| 7 | Fresh device-lifecycle/server reviewer | Device, upload, sync-service, duplicate-precheck, server build/typecheck, and modified-file checks |
|
||||
| 8 | Fresh server-boundary reviewer | Preserve unique Unicode/invalid-base64 assertions; decompression/route specs, server build/typecheck, modified files |
|
||||
| 9 | Two fresh privacy/provider reviewers | Both log exports and sentinel fields; serialize with B23-C03 in the credential store |
|
||||
| 10 | Two fresh privacy/provider reviewers | Both exports, safe category/status retention, and upload/immediate-upload/error-meta specs |
|
||||
| 11 | Two fresh privacy/sync reviewers | Close/reconnect/auth/incomplete/generic canaries, both exports, WebSocket/download/wrapper/logger specs, B13 catch |
|
||||
| 12 | Fresh server/C1 reviewer | Symbol/export/reflection closure, snapshot service specs, package build/typecheck, and modified-file checks |
|
||||
| 13 | None assigned (`none yet`) | Git/computed closure; store, simulated-client, recovery, remote-apply/conflict, targeted and scheduled sync suites |
|
||||
| 14 | Fresh encryption-test reviewer | Assertion-set subset, focused download spec, and mutations for refresh, retry, key application, and fail-closed errors |
|
||||
| 15 | None assigned (`none yet`) | Static method closure plus hydrator, DataInit, retry-integration, and sync-wrapper specs |
|
||||
| 16 | Fresh contract reviewer | Static/export/serialized-name closure, TypeScript build, sync-shell and backup-compatibility specs |
|
||||
| 17 | Fresh encryption-E2E reviewer | Symbol/reflection closure, page-object typecheck, password scenarios, scheduled encrypted SuperSync; coordinate B22-C01 |
|
||||
| 18 | Fresh database-test/B33/B36 reviewer | Isolated PostgreSQL integration, active download spec, WHERE/aggregation mutations, and modified-file checks |
|
||||
| 19 | Two fresh validation/sync reviewers | Assertion map, canonical validator, `ValidateState`, and real #7330 replay/convergence suites |
|
||||
| 20 | None assigned (`none yet`) | Every local-only key across operation payload, snapshot, and dispatch, plus hydration/local-only utility specs |
|
||||
| 21 | Fresh archive/compatibility reviewer | Legacy import/export E2E; archive service, reducer, data-repair; both parent/subtask sides; keep B36-C14 separate |
|
||||
| 22 | One test-quality reviewer | Exact case-name/literal inventory, focused package specs/typecheck, and modified-file checks |
|
||||
| 23 | Fresh B33/B36 test reviewer | Machine-readable scenario matrix; mutations for causal predicate, effective cursor, gap baseline, and response; active service/route specs and normal package tests |
|
||||
| 24 | Two fresh sync reviewers | Cursor authority, exact references, Markdown/links, and preservation of an explicit rejection fence |
|
||||
| 25 | Two fresh encryption/workflow reviewers | SuperSync-disable closure, dialog/guard cases and scheduled E2E; preserve every file-based disable method/dialog/test |
|
||||
|
||||
## Proposed next verification step
|
||||
|
||||
If a new execution amendment is authorized, admit Tier A only: eight
|
||||
candidates and nine reviewer runs. Assign two privacy/sync reviewers to
|
||||
`SSA-0045`; assign one packet-domain reviewer to each other candidate, including
|
||||
the currently unassigned `SSA-0026`. The remaining domains are
|
||||
privacy/reminder/repeat, privacy/sync, test-doc, timing-test,
|
||||
format/codec, device-lifecycle/server, and server-boundary. Any candidate later
|
||||
classified as sync-critical still requires two fresh reviewers; shrink the
|
||||
shortlist or raise the explicitly authorized run budget rather than weakening
|
||||
that rule.
|
||||
|
||||
This proposal does not authorize those runs. It also does not establish an
|
||||
implementation order. A new dependency graph should contain only candidates
|
||||
that successfully complete fresh verification.
|
||||
|
||||
## Packet-triage cutline
|
||||
|
||||
The three packet screenings nominated the following 25 groups. The outside
|
||||
count is an arithmetic reconciliation, not candidate-level comparison evidence
|
||||
or a claim that every omitted group has the same reason for omission.
|
||||
|
||||
| Stable-ID packet range | Eligible | Selected | Outside cutline | Selected stable IDs |
|
||||
| ---------------------- | -------: | -------: | --------------: | ---------------------------------------------------- |
|
||||
| `SSA-0001`–`SSA-0070` | 66 | 9 | 57 | 0002, 0026, 0030, 0034, 0045, 0047, 0058, 0066, 0068 |
|
||||
| `SSA-0071`–`SSA-0140` | 70 | 8 | 62 | 0072, 0087, 0092, 0102, 0120, 0135, 0136, 0139 |
|
||||
| `SSA-0141`–`SSA-0212` | 68 | 8 | 60 | 0141, 0142, 0143, 0151, 0155, 0173, 0190, 0209 |
|
||||
| **Total** | **204** | **25** | **179** | — |
|
||||
|
||||
## Explicit routing and exclusions
|
||||
|
||||
- The current five verified candidates stay in
|
||||
[verified-risk-reward.md](verified-risk-reward.md); they are not duplicated
|
||||
here. `SSA-0167` remains rejected, while `SSA-0043` and `SSA-0188` remain
|
||||
decision-required after Wave E.
|
||||
|
||||
| Routing outside the ranked shortlist | Stable IDs / origins | Required treatment |
|
||||
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Compatibility-gated | `SSA-0037` / B07-C03 | Do not admit until the stale SQLite rollout branch is explicitly rebased or retired; retain A6-PW-015 and issue routing. |
|
||||
| Missing combined packet/public closure | `SSA-0091` / B23-C03 plus alias B30-C01 | Produce one immutable combined packet and close the public/out-of-tree surface before admission. |
|
||||
| Atomic enforcement plan required | `SSA-0021` / B01-C01 with `SSA-0114` / B37-C01 | Keep replacement and enforcement atomic and under the existing issue; neither half is an independent cleanup. |
|
||||
| Assertion ownership incomplete | `SSA-0078` / B20-C02 | Complete the assertion-owner inventory and decomposition before considering its large test deletion. |
|
||||
| Behavior-change decision required | `SSA-0168` / B35-C15 | Obtain a maintainer decision and two sync/plugin reviewers for changed persisted-operation and plugin-event provenance. |
|
||||
| High-payoff gated reserve | `SSA-0008` / B06-C02 | First complete `SSA-0007`; then preserve both adapter suites, migration, dual-backend remote apply, scenario counts, and engine-specific lifecycle/isolation. |
|
||||
| Materially challenged privacy reserve | `SSA-0212` / C8-N01 | Characterize runtime reachability and alert/issue behavior before admission; then require privacy/error-boundary review and sentinel tests. |
|
||||
| Correctness/hardening workstream | `SSA-0033` / B08-C04; `SSA-0036` / B07-C02; `SSA-0039` / B10-C02 | Route through bugfix or hardening work, not behavior-preserving simplification admission. |
|
||||
| Already-tracked evidence | `SSA-0006` / B05-C05; `SSA-0022` / B01-C02; `SSA-0080` / B20-C04; `SSA-0114`–`SSA-0116` / B37-C01–C03 | Keep under existing A5/A6/issue ownership. The links are routing evidence, not fresh verification. |
|
||||
| Source-named capacity reserves below cutline | `SSA-0014` / B03-C02; `SSA-0129` / B29-C04 | Keep visible as reserves without inventing a new common value band; coordinate SSA-0129 with, but keep it separate from, SSA-0078. |
|
||||
| All other omitted groups | Remaining groups outside the shortlist | Retain their packet-specific consumer, format, scenario, reviewer, compatibility, and existing-work gates. |
|
||||
|
||||
High-LOC test proposals remain unverified; deletion size alone does not
|
||||
outweigh incomplete assertion ownership or validation cost. The 179 groups
|
||||
outside the shortlist remain exactly `discovered/proposed, unverified`. The
|
||||
25 selected groups are ordered, but the cutline is not a complete value ranking
|
||||
of all 204 groups: omission is neither rejection nor proof of lower reward.
|
||||
|
||||
## Provenance and frozen boundaries
|
||||
|
||||
- Findings SHA-256:
|
||||
`83acd393736396f8b9de33b961dbab82347443fd8fa9e9f410cb5fc5aab0c8e9`
|
||||
- Verification SHA-256:
|
||||
`9dda34dbcba5390297de172dcfd1eacc1bc27e32ed174f3245298567d563f18d`
|
||||
- Retained-register SHA-256:
|
||||
`ac42fde4d895e1993561039e0a7169696f9db796124dbc40f5704907da9dee4d`
|
||||
- D1 mapping SHA-256:
|
||||
`4904a4cbf41d6b1c328e5f63e27f0d12242f1fa10c31edf654b617833cf4aa2a`
|
||||
|
||||
Do not edit the frozen plan or audit artifacts to reflect this derived
|
||||
ordering. Future verification and implementation outcomes belong in new
|
||||
execution records linked back to the immutable stable ID and revision.
|
||||
1758
docs/research/sync-simplification-audit/retained.md
Normal file
1758
docs/research/sync-simplification-audit/retained.md
Normal file
File diff suppressed because it is too large
Load diff
1049
docs/research/sync-simplification-audit/verification.md
Normal file
1049
docs/research/sync-simplification-audit/verification.md
Normal file
File diff suppressed because it is too large
Load diff
163
docs/research/sync-simplification-audit/verified-risk-reward.md
Normal file
163
docs/research/sync-simplification-audit/verified-risk-reward.md
Normal file
|
|
@ -0,0 +1,163 @@
|
|||
# Verified sync simplification priorities
|
||||
|
||||
- Status: post-audit derived decision guide
|
||||
- Date: 2026-07-17
|
||||
- Source audit snapshot: baseline `5d02ec86…2651`, findings
|
||||
`83acd393…c8e9`, retained `ac42fde4…e4d`, verification
|
||||
`9dda34db…f18d`
|
||||
|
||||
This document orders only the five candidates that reached a clean Wave E
|
||||
`verified` disposition. It is derived from [verification.md](verification.md),
|
||||
[findings.md](findings.md), and [retained.md](retained.md); it is not part of
|
||||
the frozen audit baseline and does not change any candidate's evidence or
|
||||
disposition.
|
||||
|
||||
## Scope and limits
|
||||
|
||||
- Five verified candidates are ranked for implementation planning.
|
||||
- One rejected and two decision-required candidates are listed separately and
|
||||
are not implementation candidates.
|
||||
- The remaining 206 origins / 204 stable groups remain
|
||||
`discovered/proposed, unverified` and are not ranked.
|
||||
- The ordering is qualitative. It does not invent a synthetic score that the
|
||||
audit never measured.
|
||||
- Audit verification is not implementation authorization. Each implementation
|
||||
still needs a separately approved change and its required tests.
|
||||
|
||||
## Ordering method
|
||||
|
||||
Candidates are compared in this order:
|
||||
|
||||
1. Behavioral risk and reversibility.
|
||||
2. User/data-protection payoff and maintenance benefit.
|
||||
3. Evidence confidence.
|
||||
4. Validation cost and blast radius.
|
||||
5. F1 dependency and integration constraints.
|
||||
|
||||
All five have reproduced evidence and low behavioral risk. Their order is
|
||||
therefore driven mainly by privacy payoff, validation cost, compatibility
|
||||
sensitivity, and dependency sequencing.
|
||||
|
||||
N42 and N211 share the same overall risk/reward tier. Their `4a`/`4b` labels
|
||||
follow F1's recommended integration sequence; they do not claim a measured
|
||||
benefit or confidence difference between the two candidates.
|
||||
|
||||
## Risk/reward matrix
|
||||
|
||||
| Priority | Candidate | Reward | Risk and cost | Why it belongs here |
|
||||
| :------: | ----------------------------------------------------------------- | ----------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| 1 | `SSA-0025` / N25 — stop retaining decrypted JSON samples | High privacy payoff; medium maintenance benefit | Low behavioral risk; medium validation | Removes plaintext retention from error objects while preserving recovery and routing. It has the clearest direct user-data benefit. |
|
||||
| 2 | `SSA-0009` / N09 — remove duplicate final-upgrade mock assertions | Medium maintenance benefit | Low behavioral risk; small validation | A small, reversible test-only deletion backed by the real IndexedDB descriptor test and version-threshold coverage. |
|
||||
| 3 | `SSA-0202` / N202 — remove unused SuperSync E2E helper APIs | Medium maintenance benefit | Low behavioral risk; small validation | Removes 13 unused unpublished helpers and is isolated from production and the application integration harness. |
|
||||
| 4a | `SSA-0042` / N42 — remove unused legacy database writers | Medium maintenance benefit | Low behavioral risk; medium validation; compatibility-sensitive area | The methods are unused, but the surrounding legacy migration and recovery boundary justifies later integration and broader validation. |
|
||||
| 4b | `SSA-0211` / N211 — remove definition-only integration APIs | Medium maintenance benefit | Low behavioral risk; medium validation; widest test-harness surface | Removes 17 APIs, but must retain call-history storage and the awaited zero-latency ordering boundary across five direct harness consumers. |
|
||||
|
||||
The matrix has no high-risk verified row. That is a result of fast-track
|
||||
admission deliberately preferring a smaller low-risk shortlist, not evidence
|
||||
that the broader findings register is low risk.
|
||||
|
||||
## Ranked implementation notes
|
||||
|
||||
### 1. SSA-0025 — decrypted JSON sample retention
|
||||
|
||||
- **Revision:**
|
||||
`79a3da4fd738460559d70b974ef52eb8093cc3c9cfc07b7145fe5a8f32a98ff4`
|
||||
- **Reward:** removes an unnecessary plaintext snippet from a diagnostic error
|
||||
object and reduces the chance of user data entering exported diagnostics.
|
||||
- **Guardrails:** preserve `JsonParseError` identity, safe message, numeric
|
||||
parse position, fail-closed parsing/decryption, `.bak` recovery, wrapper
|
||||
routing, and force-overwrite behavior.
|
||||
- **Required proof:** error/encryption/wrapper/file-adapter recovery specs plus
|
||||
a sentinel showing plaintext is absent from own properties, JSON
|
||||
serialization, and exported logs.
|
||||
- **Dependency:** must precede N42 and N211 in the integrated roadmap because
|
||||
of shared wrapper/file-adapter evidence boundaries.
|
||||
|
||||
### 2. SSA-0009 — duplicate IndexedDB upgrade test
|
||||
|
||||
- **Revision:**
|
||||
`1dd864b5c919289ea9624bb3547d6332f23a48cf9b5f3621aee7f4623c914ff9`
|
||||
- **Reward:** removes a duplicated mocked representation of the final schema
|
||||
and its maintenance burden.
|
||||
- **Guardrails:** retain every historical threshold test, v7 metadata seeding,
|
||||
v10 downgrade protection, and the real v0-to-current descriptor check.
|
||||
- **Required proof:** both focused upgrade specs and a mutation check showing
|
||||
the real descriptor guard fails when a store or index drifts.
|
||||
- **Dependency:** should precede N42 so the destination-schema evidence is
|
||||
stable before changing the legacy source bridge.
|
||||
|
||||
### 3. SSA-0202 — unused SuperSync E2E helpers
|
||||
|
||||
- **Revision:**
|
||||
`1a69b3ad2f75e847a37ac3cfdaea416cf9ca0c37cd00a087000e214b28ea6d5a`
|
||||
- **Reward:** removes 13 unused exports and reduces the apparent E2E helper
|
||||
vocabulary without deleting any scenario.
|
||||
- **Guardrails:** delete only the verified symbols and imports made unused;
|
||||
retain every helper with a live scenario consumer.
|
||||
- **Required proof:** check both helper files, compile/list E2E discovery, and
|
||||
confirm no barrel, namespace, dynamic, or external harness consumer appears.
|
||||
- **Dependency:** isolated; it may be developed in parallel with N25 and N09.
|
||||
|
||||
### 4a. SSA-0042 — unused LegacyPfDbService writers
|
||||
|
||||
- **Revision:**
|
||||
`68dff22a1f2ee21c97156cfb977ff5adb4209cd20bbad3f75d6f414d73f3b902`
|
||||
- **Reward:** removes two dead internal methods and their direct-only tests.
|
||||
- **Guardrails:** retain every legacy database name, version, store, key, read,
|
||||
generic save, metadata/client-ID path, migration lock, archive migration,
|
||||
reminder cleanup, and recovery path.
|
||||
- **Required proof:** legacy service, startup, reminder, archive migration, and
|
||||
operation-log migration/recovery tests.
|
||||
- **Dependency:** integrate only after N25 and N09, then rerun the shared
|
||||
wrapper and persistence-compatibility evidence.
|
||||
|
||||
### 4b. SSA-0211 — definition-only integration harness APIs
|
||||
|
||||
- **Revision:**
|
||||
`d75667b114fd1b86c1661d888f6dd672b64c480601f6b8a2b6c022ea38fc312a`
|
||||
- **Reward:** removes 17 unused test APIs and stale example text from five
|
||||
helper files.
|
||||
- **Guardrails:** retain provider CAS/error behavior, live `getCallsTo`, its
|
||||
call-history storage, reset behavior, ready-by-default behavior, and the
|
||||
awaited zero-latency asynchronous boundary.
|
||||
- **Required proof:** check all five helper files, run TypeScript discovery,
|
||||
and run the five direct file-based-sync integration consumers.
|
||||
- **Dependency:** integrate after N25; it remains independent of N42 once that
|
||||
edge has been satisfied.
|
||||
|
||||
## Development and integration order
|
||||
|
||||
The risk/reward ranking and F1 dependency graph permit this execution shape:
|
||||
|
||||
1. Develop N25, N09, and N202 independently.
|
||||
2. Integrate them sequentially as N25 → N09 → N202.
|
||||
3. After N25 and N09 are integrated, develop N42 and N211 independently.
|
||||
4. Integrate N42, rerun legacy migration/recovery evidence, then integrate
|
||||
N211 and rerun its five direct integration suites.
|
||||
|
||||
Keep every stable ID in its own reviewable implementation slice. Do not bundle
|
||||
the rejected or decision-required records into these changes.
|
||||
|
||||
## Explicitly excluded from the ranking
|
||||
|
||||
| Candidate | Disposition | Reason |
|
||||
| -------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------- |
|
||||
| `SSA-0167` / B35-C14 | Rejected | Its immutable packet missed a second exportable calendar-content log. A wider two-sink proposal is unverified. |
|
||||
| `SSA-0043` / B12-C01 | Decision-required | Static evidence was favorable, but the verifier did not complete the mandatory after-baseline reproduction. |
|
||||
| `SSA-0188` / B35-C35 | Decision-required | The fresh verifier session returned neither a terminal report nor an after-baseline reproduction. |
|
||||
|
||||
The other 206 origins are research inventory, not an ordered implementation
|
||||
queue. Ranking them would require a separate evidence pass that assigns the
|
||||
same four bands and resolves compatibility, consumer, and validation gaps
|
||||
without modifying the frozen audit records.
|
||||
|
||||
## How to use this document
|
||||
|
||||
- Use this file for prioritization and sequencing only.
|
||||
- Use `verification.md` for authoritative verifier evidence and F1 edges.
|
||||
- Use `findings.md` for the immutable candidate packet and revision hash.
|
||||
- Use `retained.md` for boundaries that must survive implementation.
|
||||
- At implementation time, run `npm run checkFile <filepath>` for every changed
|
||||
TypeScript file and the candidate-specific tests listed above.
|
||||
- Record implementation PRs and outcomes in a new document or issue; do not
|
||||
rewrite the frozen audit artifacts.
|
||||
Loading…
Add table
Add a link
Reference in a new issue