Ripple

Change one thing. Repair only what depends on it. A stateful Alexa+ simulation with fee-aware consent, honest recovery, and causal receipts.

Comment

Inspiration

One changed flight can leave a whole visit out of sync. The calendar moves, but groceries are already dispatched, dinner is booked for the wrong night, and the pickup reminder still fires on Friday. A useful agentic assistant should understand those dependencies, explain the consequences, and ask before a costly change.

Ripple explores that experience through a clearly labelled Alexa+ simulation: change one fact, repair what depends on it, and leave unrelated commitments alone.

What it does

Ripple coordinates a fictional three-day family visit across five simulated services: calendar, grocery delivery, restaurant reservations, household routines, and pickup reminders.

A changed arrival, departure, guest count, or budget produces a preview before anything executes. The dependency graph identifies affected commitments and shows the rest as untouched. Each operation carries its cause, price, lifecycle state, and an approve/decline decision.

The difficult cases are the point:

  • A dispatched grocery order cannot be undone. Its cost remains, and a separately priced top-up needs a separate decision.
  • A cancellation fee that changes after approval triggers a fresh quote and consent. It is never silently charged at the new price.
  • Declined choices stay declined while the facts remain unchanged.
  • Pending decisions and the causal ledger survive a reload. Later, “What changed because of the flight?” distinguishes proposed, approved, and applied effects using persisted per-operation provenance and status.
  • Repeating an unchanged absolute fact is a no-op. Arbitrary supported values can also be entered through the fact editor.

How I built it

The TypeScript engine owns typed facts, desired-state reconciliation, lifecycle policies, consent binding, and a replayable journal. It has no external I/O. A React/Vite app presents the plan, natural-language composer, direct fact editor, explicit simulated clock, and causal receipts.

An optional localhost-only MCP developer inspector uses the same engine. It is not an Alexa add-on or a consumer integration. Its optional explicit payload-hash/revision checks are documented separately from its simpler operation-ID mode.

Development was AI-assisted with Devin, followed by separate source review and browser acceptance testing. Review uncovered real implementation defects around stale facts, repeated approvals, fee drift, declined alternatives, persistence, and historical attribution; those were corrected and checked with targeted automated regressions and repeat browser tests.

Verification and challenges

The deployed merge commit c94a35364e89b6556614aa635673c8d35739bf54 passed lint, strict type checking, 94 automated tests (70 engine, 13 simulator, and 11 MCP), and the production build; its GitHub Pages deployment succeeded. The property suite exercises 1,200 randomized action sequences per run. Tests cover idempotence, unaffected commitments, consent and fees, replay equality, and provenance. These are regression checks, not a proof of correctness or a user study.

Browser checks covered the deployed flow, reload persistence, unsupported-command clarification, mobile overflow, and keyboard modal focus. The demo is 1:48 of actual app footage with readable captions, captured at commit 9a7734ed031e0dfc40bb4670201ad85b05a7ade3.

The hardest design decision was making partial success honest. A changed plan does not guarantee that every service can comply, and a fee is not a saving. Ripple keeps those consequences visible instead of pretending that recovery always succeeds.

What I learned and what's next

Deterministic state and an injected clock make subtle agentic failures reproducible. The next engineering work is concurrent-session handling, richer fictional refund/waitlist policies, and validation against official Alexa+ preview tooling if entrant access becomes available.

Honest limits

This is a simulated Alexa+ experience, with no Alexa runtime connection, AWS service use, real bookings, purchases, calendar writes, or private household data. Prices and policies are fictional. State is browser-local and intended for one tab. The intent parser is bounded; voice input is not implemented, and optional text-to-speech uses the browser. The simulated clock is UTC-labelled and does not model daylight saving. No human user study or additional teammate contributions are claimed.

Product feedback: https://github.com/sharonbasovich/ripple-alexa/blob/main/docs/feedback.md Friction log: https://github.com/sharonbasovich/ripple-alexa/blob/main/docs/friction-log.md

Built With

Share this project:

Updates

Submission history