feat: build the Icarus-owned typed Convex wrapper

[SunkenInTime]

Accepted architecture

Icarus keeps convex_flutter as the native runtime and owns the typed Dart layer above it. A committed, scrubbed Convex function spec generates one fail-closed Dart API over normalized native and web transports. Closed protocol-v3 operations and typed repository mappings replace the generic JSON boundary.

ADR: docs/adr/0001-icarus-owns-typed-convex-wrapper.md
Implementation handoff: docs/cloud_sync_refactor/typed_convex_wrapper_implementation_handoff.html

Phase commits

• Phase 1, immutable queued op identity: 3ebcdc1
• Phase 2, closed protocol version 3: 25520b2
• Phase 3, closed public validators and scrubbed snapshots: 13a8b97
• Phase 4, fail-closed Dart generator and generated API: 491f6f2
• Phase 5, normalized native and web transports: 40f87fe
• Phase 6, repository migration and one folder-tree subscription: 8ff0d5c
• Phase 7, CI drift gates and legacy-path removal: 79e7234, eaf4abe

Release acceptance also uncovered and fixed existing release-only UI/platform blockers in d9e877c, ddcc080, 918354e, 8a178fe, and 4aa4ed0. Completed lineup markers remain editable in 9c32bd9; native lineup hydration fails closed in 8adba7c; editor cloud export and lossless round-trip are fixed in 9fc7396.

Contract and generated surface

• Protocol v3 is a closed union of 13 operation variants.
• All 42 public Convex functions now have explicit return validators.
• The scrubbed error contract contains 34 stable error codes.
• The Icarus-owned generator rejects unknown validator/return shapes and produces deterministic output.
• Native and web transports preserve structured Convex errors.
• Repositories use generated API members instead of raw public route strings.
• Folder state uses one recursive tree subscription; strategies remain separately subscribed.

Verification

• npx tsc --noEmit
• npm run test:convex: 25 passed
• Contract audit: 42 functions and 34 error codes
• Generator analyze/tests: 9 passed; generated twice with no diff; repeated in clean clones
• Architecture tests: 5 passed
• fvm flutter analyze --no-fatal-infos: no errors; six pre-existing info lints
• fvm flutter test --concurrency=1: 383 passed
• Both native Rust package test suites passed
• Release web build passed
• Universal release macOS build passed with --no-tree-shake-icons: 98.2 MB. The final arm64 acceptance build passed at 55.3 MB; strict code-sign verification and sandbox/network/file entitlements passed.

The exact macOS release command without the icon flag still fails on the repository's pre-existing runtime-created IconData tree-shake limitation.

Runtime gauntlet

The protocol-v3 50,000-operation run completed with exact canonical equality, 45,500 acknowledgements, 4,500 intentional rejections, zero unresolved operations, reconnect/auth coverage, and exactly-once settlement. Wall time was 87.607 seconds and maximum RSS was 269,451,264 bytes.

A before/after performance claim is intentionally omitted: the historical artifact compares Dartvex with convex_flutter, not this wrapper before and after, so it is not a valid baseline.

Live release evidence

• Signed-out macOS local library remained intact.
• Signing in preserved the same local library.
• macOS-created nested folders, strategy pages, text, and a completed lineup appeared on web.
• A web folder rename arrived in the already-running macOS release without reload.
• A web strategy move arrived in the already-running macOS release without reload.
• Native Convex float64 indexes hydrated the completed Astra/Gravity Well lineup instead of dropping it and authoring a false tombstone.
• The completed Gravity Well marker remained draggable; the UI reached Synced, and Convex advanced its revision with deleted: false.
• A fresh final-SHA macOS release launch restored the signed-in session and reconnected to the cloud library.
• The editor exported the cloud strategy, imported it as a fresh local strategy, and re-exported canonically identical JSON across all three pages and the completed lineup.
• The temporary local strategy and all exact typed-wrapper* cloud fixtures were removed after acceptance; the pre-existing local library was left intact.

Current blocker

The PR remains draft. The isolated Convex contract CI job deliberately fails closed because the repository does not yet have CONVEX_PREVIEW_DEPLOY_KEY. Add that repository secret to let CI create the required isolated preview deployment. Greptile will be retriggered only after the full check suite is green.

Known non-goals

No Convex replacement, Dartvex adoption, local Hive library migration, .ica format change, or general-purpose package publication.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 40750a1f-b8d5-4105-9a8b-cbe9dbcc73b7

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

This change adds a typed Convex client boundary for cloud library and strategy synchronization, durable settlement for queued strategy operations, and checks that generated client code remains aligned with its contract.

The reviewed cloud paths preserve folder hierarchy integrity, prevent duplicate replay effects, retain unresolved local work, and stop subscriptions after invalid contract data. The focused backend and Flutter checks completed successfully.

Confidence Score: 5/5

The verified cloud synchronization behaviors are safe to merge.

Focused execution covered each reviewed failure mode: self and descendant folder moves were rejected; a replay after response loss left one persisted change; rejected outbox work survived both reconciliation and a failed attention-state write; and malformed subscription payloads cancelled the stream before a later stale update could arrive.

Files Needing Attention: No additional files need attention for the verified behaviors.

T-Rex Logs

What T-Rex did

• A focused test removed the ancestor-walk guard to verify the folder move behavior, and then re-enabled the guard to confirm moves are rejected and the tree remains unchanged.
• A focused Convex test submitted an operation, treated its successful response as lost, and then replayed the exact same client operation; the first submission applied at revision 1, and the replay was a no-op with exactly one persisted element and one operation event.
• Focused Flutter scenarios verified that a persisted rejected-attention record survives normal reconciliation, and when saving a rejected acknowledgement as attention work was forced to fail, the original operation was restored as durable retry work rather than discarded.
• A scripted subscription emitted a valid value, then a contract-violating value, followed by a stale value; both transport normalization and generated decoding reported the error, cancelled the underlying subscription, and prevented the stale value from being delivered.
• Combined validation across guard behavior, replay boundary tests, and contract safety was captured: the guard and mutation checks prevent cycles, replay tests show persistence and no-op behavior on repeated operations, and safety tests verify durable handling of subscription and attention work, with all Flutter tests passing.

_{Ran code and verified through T-Rex}

_{Reviews (8): Last reviewed commit: "fix: recover sync batch after ack persis..." | Re-trigger Greptile}

[SunkenInTime]

@greptileai

Dismissed because a newer commit was pushed; Greptile will re-review the current head.

[SunkenInTime]

@greptileai

Dismissed because a newer commit was pushed; Greptile will re-review the current head.

[SunkenInTime]

@greptile-apps

[SunkenInTime]

Fixed the failed cloud-folder deletion fall-through in 4cda0a8 and added regression coverage for both rejection and success. Focused analysis is clean and all 385 Flutter tests pass.

@greptileai

[SunkenInTime]

Resolved the T-Rex Flutter compatibility blocker in 9f4c7cf by locking lucide_icons_flutter 3.1.17. The package no longer subclasses final IconData. The 36 tests named in the review pass, the full 385-test Flutter suite passes, and analysis has only the six pre-existing info lints.

@greptileai

[SunkenInTime]

Fixed cyclic cloud-folder moves in b9775b5. folders:move now checks the proposed parent's ancestry before patching and rejects self-parent, descendant-parent, pre-existing cyclic ancestry, and broken ancestry. New handler tests prove both reported moves reject without changing stored parent pointers. All 27 Convex tests pass, TypeScript is clean, and contract snapshots remain current.

@greptileai

[SunkenInTime]

@greptileai please review the latest head (fbad1e7). The acknowledgement persistence failure now propagates to flushNow, which restores the batch from inFlight to the durable retry queue. Added regression coverage for both accepted-ack removal failure and rejected-ack attention-write failure; full Flutter suite passes (387 tests).