Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 8 additions & 4 deletions docs/ALERTS.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Buffer threshold monitoring

Updated September 20, 2026. This runbook separates local rehearsal, hosted dry runs, and configured Discord sending. The current evidence and outstanding gates are in [the integration matrix](BUFFER-INTEGRATION-STATUS.md).
Updated October 1, 2026. This runbook separates local rehearsal, hosted dry runs, and configured Discord or signed-webhook sending. The current evidence and outstanding gates are in [the integration matrix](BUFFER-INTEGRATION-STATUS.md).

Buffer checks **observed Velocity cross-margin maintenance headroom in USD**, or, since 28 September 2026, the **unsigned distance in percent from the current oracle to one position's estimated liquidation price** (model `cross-margin-hold-others-v1`, see [WEBHOOK-ALERTS.md](WEBHOOK-ALERTS.md)). It never alerts on the price slider. A rule binds an authenticated cloud owner, Solana authority/subaccount, provider/network, metric (and market for liquidation distance), exact threshold and direction, cadence, timezone, cooldown, hysteresis, destination reference (Discord or signed webhook), enabled state, and version. Watching a public address does not prove ownership or require signing.

Expand All @@ -23,7 +23,7 @@ The additive migration `20260920020000_hosted_monitoring.sql` extends the existi
- Cadence, cooldown and hysteresis survive unavailable observations and restarts. Pausing, deleting or changing a rule version invalidates pending work. History is retained; a remotely accepted message cannot be recalled.
- The scheduler is bounded server work, not a browser timer. A heartbeat expires after 180 seconds, including on a page left open. UI separates attempted check, last fresh observation, next check, provider acceptance and matching receipt.

## Exactly one outbound provider: Discord
## Outbound destinations: Discord and signed webhooks

See [the Discord contract and setup](DISCORD-ALERTS.md) for exact configuration, official API references, quotas and sanitized preview. `BUFFER_DISCORD_DESTINATIONS_JSON` contains platform-admin destination references and an explicit allowed-owner list. Tokens stay in server environment variables. Users cannot paste arbitrary fetch URLs. Metadata GET verifies the configured channel; webhook calls use a fixed Discord HTTPS origin/path with redirects rejected.

Expand All @@ -33,6 +33,8 @@ States are `queued`, `sending`, `accepted_by_provider`, `delivered`, `failed`, `

Discord webhook POST has no documented idempotency key. An ambiguous POST or an expired in-flight send becomes `unknown_outcome`; it is never blindly resent. If the message ID was durably recorded, the worker can reconcile it by GET without another POST. Retries are bounded and safe rate-limit responses respect validated Retry-After with jitter. Permanent credential/destination failures require intervention. No database outbox promises exactly-once external delivery.

Signed webhooks use server-only `BUFFER_WEBHOOK_DESTINATIONS_JSON`, explicit owner allowlists, and HMAC authentication. Their verification confirms configuration policy; it does not contact the receiver. A receiver's successful HTTP response establishes delivery acknowledgement, without Discord's separate message read-back. See [the webhook contract](WEBHOOK-ALERTS.md) for configuration, receipt semantics, retry limits, and rotation. Neither destination is configured by pasting an arbitrary URL into the app.

## Local rehearsal command

Use Node 24 and the existing npm lockfile:
Expand All @@ -50,14 +52,16 @@ SQLite `.local/alerts.sqlite` uses WAL, full synchronization and transactional r
1. Apply the reviewed additive migration and verify RLS/function privileges. Use the existing Buffer Supabase project; do not create another project or replace its report tables.
2. Generate distinct random worker and cron credentials. Store the worker hash in the private credential row, and put the actual values in server-only Vercel variables. Configure `BUFFER_ALERT_SEND_ENABLED=false` and `BUFFER_ALERT_NOTIFICATION_MODE=test` initially. Deploy before activating the scheduler.
3. Use Supabase Pro `pg_cron` + pinned synchronous `http` 1.6 HEAD to invoke the fixed production worker once per minute. Keep the cron credential in Supabase Vault. [Deployment](DEPLOYMENT.md) records the activation/rollback procedure. Check actual cron result and persisted heartbeat; environment variables alone do not prove execution.
4. Configure exactly one Discord destination for the intended confirmed Supabase owner. Verify its metadata; prepare the exact redacted message and destination. Obtain recipient-send authorization before turning on sends. Existing signup/recovery email stays disabled independently.
5. Save an authorized test threshold around a real current observation. Confirm event ID, rule version, source slot/time, provider message ID and matching channel receipt. Retain redacted evidence, then pause/delete the test rule. Do not call this step verified until a real receipt exists.
4. Configure a reviewed Discord or signed-webhook destination for the intended confirmed Supabase owner. Verify the destination according to its provider contract; prepare the exact redacted message and destination. Obtain recipient-send authorization before turning on sends. Existing signup/recovery email stays disabled independently.
5. Save an authorized test threshold around a real current observation. Confirm event ID, rule version, source slot/time, and the destination-specific delivery receipt. Retain redacted evidence, then pause/delete the test rule. Do not call this step verified until a real receipt exists.

To pause: disable the scheduler job and set sending false. To rotate: first disable sends, rotate the webhook/token and configuration fingerprint, reverify the channel, invalidate old pending work, redeploy, then reenable only after authorization. Never reuse unknown-outcome events as fresh sends. Inspect unavailable reasons, heartbeat age and outbox state; do not erase a damaged journal to make the UI green. Rollback leaves the additive schema/RLS in place, disables the job and sending, and promotes the previous known-good application.

## Verification

Unit suites cover exact threshold semantics, provider contracts, response bounds, invalid inputs, owner/session changes, immutable report semantics and crash outcomes. PGlite scripts exercise actual migrations, RLS, two-owner denial, uniqueness and fenced transitions. Real-process SQLite tests exercise independent concurrent runners and crash rollback. Browser tests intercept auth/provider/monitoring transport and explicitly check fixture/live separation, accepted-versus-receipt UI, unknown outcomes, expired heartbeat, unavailable storage and sign-out. These deterministic tests never send to Discord. Hosted scheduler execution and actual recipient delivery have separate evidence gates.

On October 1, 2026 at 06:23 UTC, the production database showed 30 successful scheduled cron runs and 30 completed protected worker runs in the preceding 30 minutes. The worker remained in `dry_run` mode. This verifies execution of the scheduler, not outbound delivery.


The narrow worker processes at most one work item per minute; configured cadence is a minimum interval, not a guaranteed maximum notification delay under backlog. Limits are 20 rules per owner, 100 events per owner per day, 10 send attempts per owner per hour, 3 send attempts and 5 receipt lookups per event. Stale queued events are suppressed after 120seconds rather than dispatched after an outage. Completed/suppressed unreferenced history is pruned after 30 days in bounded batches; unresolved outcomes remain available for investigation. Fresh deliveries take precedence over receipt retries so a slow receipt cannot expire another event's send window.
9 changes: 6 additions & 3 deletions docs/DEPLOYMENT.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Deployment and cloud configuration

**Last updated:** September 20, 2026. Production deployment is now authorized. The reviewed alert hardening and function-permission migrations have been applied; see [the release record](RELEASE-2026-09-20.md) for the final deployment and verification result.
**Last updated:** October 1, 2026. The reviewed alert hardening, function-permission and liquidation-sentinel migrations have been applied. [The September 20 release record](RELEASE-2026-09-20.md) documents the initial hosted-monitoring activation; later verification is described below.

Buffer runs on Node 24 with Next.js App Router. `/` is the public website, `/app` is the public explorer with live Velocity as the default, modeled Pacifica reads, and inventory-only Jupiter Perps, and `/auth` contains optional email/password sign-in. The protocol selector also exposes the explicitly paused legacy Drift reader. Scenario functionality, live public reads, device-local reports, and downloads work without a cloud account.

Expand All @@ -27,6 +27,8 @@ The default live provider is the official `@velocity-exchange/sdk` **0.23.1**, b

The server-side RPC endpoint used by Velocity, Jupiter, and legacy Drift must be Solana **mainnet-beta**. Those providers reject a different genesis hash, check program ownership and account identity, and never substitute a sample when a live read fails. Requests have an 18-second abort deadline; Vercel functions need at least 30 seconds. Each process allows 60 reads per minute and four concurrent reads. The live-read route also applies the configured distributed limit when available; see `src/server/rate-limit.ts` and the environment template for its current readiness. A dedicated RPC is still needed for sustained provider capacity. Pacifica uses its fixed HTTPS API boundary and its own timestamp freshness rule.

Buffer's connection to mainnet is read-only. The wallet button requests a public address through Wallet Standard; providers cannot sign, submit or settle transactions. “Settlement” in provider metadata describes the venue's accounting asset, not an execution feature in Buffer.

## Supabase

Create or use the dedicated Buffer project **`vhbngdatlowfnwaymvuq`** in **operatoruplift's Org**. Apply all files in `supabase/migrations/` in timestamp order through the Supabase migration workflow. They create `saved_reports`, the user/date index, authenticated select/insert/delete grants, owner-only row-level security, and strict report/title constraints, plus the additive owner-scoped alert pipeline tables (`alert_rules`, `alert_events`, and `alert_outbox`). Anonymous users have no table privileges. Reports are immutable historical JSON records with a maximum size of 256 KiB and are never inputs to the live reader.
Expand All @@ -44,7 +46,7 @@ The browser SDK manages sessions and refreshes tokens. Database RLS is the autho

### Provisioning status

The dedicated project **Buffer** (`vhbngdatlowfnwaymvuq`, US East) was created in **operatoruplift's Org** after the organization was upgraded to Pro. Supabase quoted **$10/month** for the additional project. Both saved-report migrations and the September 15 additive alert migration are recorded as applied; the September 19 hardening and September 20 function-permission migrations are now applied; owner isolation, malformed JSON rejection, restricted insert columns, query indexing, and the alert tables' RLS posture have been verified. The shipped browser monitor uses bounded localStorage state and a local mock sink, so hosted delivery is not implied by the production deploy; a hosted provider-polling worker and verified external destination are still required. See [database verification](DATABASE-VERIFICATION.md) and the [alert runbook](ALERTS.md).
The dedicated project **Buffer** (`vhbngdatlowfnwaymvuq`, US East) was created in **operatoruplift's Org** after the organization was upgraded to Pro. Saved-report, alert hardening, owner-scoped hosted-monitoring, and liquidation-sentinel migrations are applied. The hosted worker and minute scheduler are active; the local rehearsal remains a separate experience. A read-only production check on October 1 at 06:23 UTC found 30 successful cron runs and 30 completed protected worker runs in the preceding 30 minutes, all in `dry_run` mode. Outbound notification delivery is not yet verified. See [database verification](DATABASE-VERIFICATION.md), [the alert runbook](ALERTS.md), and [webhook migration evidence](WEBHOOK-ALERTS.md).

The original implementation recorded confirmed-account password sign-in and private report CRUD with disposable confirmed accounts. That is historical evidence from the original version. The current redesign's browser auth and report coverage uses the installed Supabase SDK with intercepted/mock transport; it does not prove a current production auth or email journey. Production SMTP delivery, redirect allowlists, Auth password policy, and compromised-password screening still require management-side configuration and verification. Do not treat the built-in restricted Supabase mail sender as public production signup delivery.

Expand All @@ -57,7 +59,7 @@ The latest production verification also exercises `/brand-kit`, `/api/config`, a

## Installable app

See [PWA details](PWA.md) for supported browser installation and offline behavior. The same responsive web application works on mobile and desktop, and the service worker provides a clearly labeled fixed sample offline. Native App Store/Play Store packages and signed desktop installers are outside this delivery.
See [PWA details](PWA.md) for supported browser installation and offline behavior. The same responsive web application works on mobile and desktop, and the service worker provides a clearly labeled fixed sample offline. The repository also contains an [Android Web Shell project](seeker-and-pwa.md); physical-device installation and store distribution require separate verification. App Store/Play Store releases and signed desktop installers are outside the web deployment.

## Hosted monitoring addition — September 20

Expand All @@ -70,6 +72,7 @@ The current monitoring implementation adds authenticated `/api/monitoring` confi
| `BUFFER_ALERT_SEND_ENABLED` | Server only | Defaults to false. Keep false until an exact destination and test message are authorized. |
| `BUFFER_ALERT_NOTIFICATION_MODE` | Server only | Defaults to `test`; labels genuine live observations as test notifications. `production` is a deliberate separate choice. |
| `BUFFER_DISCORD_DESTINATIONS_JSON` | Server only | One reviewed Discord configuration with webhook credentials, channel ID, stable config UUID and explicit allowed owner UUIDs. See the exact schema in the provider runbook. |
| `BUFFER_WEBHOOK_DESTINATIONS_JSON` | Server only | Reviewed HTTPS receivers, HMAC secrets, stable destination UUIDs and explicit allowed owner UUIDs. See [the signed-webhook contract](WEBHOOK-ALERTS.md). |

Apply `20260920020000_hosted_monitoring.sql` only after its PostgreSQL verification passes. Initialize `private.buffer_monitor_credentials` with a SHA-256 hash through the administrator connection. Never commit the plaintext secret or put it in a URL. Deploy the new server variables before scheduling. Worker routes declare 60-second duration; their coordinator bounds due-provider work and dispatch. Browser requests time out after 45 seconds.

Expand Down
21 changes: 21 additions & 0 deletions docs/LAUNCH-FILM.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# Buffer launch film

The launch film appears at [/demo#launch](https://bufferonsolana.vercel.app/demo#launch), before the three narrated product films. The landing page links to it from the product essentials strip. Playback is optional, with native controls, inline mobile playback, and no autoplay or video preload. The poster loads before a viewer starts the film.

The user supplied `buffer-reel-30s-master.mp4` on October 1, 2026. The original master remains unchanged. The hosted derivative preserves the 30-second duration, 1920 × 1080 picture, 60 fps motion, and original music and interface-sound mix. Public assets are `/videos/buffer-launch.mp4` and `/videos/buffer-launch-poster.jpg`, with the cache revision `20261001`.

The fast-start H.264/AAC derivative is 10,432,064 bytes, 78% smaller than the master. All 1,800 frames decoded successfully; the AAC payload is identical to the source. The source mix measures −14.1 LUFS integrated and −1.8 dB true peak. The 1600 × 900 poster is taken from the final Buffer scene.

| Asset | SHA-256 |
| --- | --- |
| Supplied master | `a31dbdc8938a4057ec9132a86a0043dbe32ffdcf0a8c9ce5ce1c95ab98b7b592` |
| Hosted film | `fd92e554285f7507ebbd98e33e504508e54071b5880eb4fcca53edcd1d440fc3` |
| Poster | `1b6946ec9b8e7a669223579876d4f2b2db0e178e855772ab4466a4b6f3fb9ba3` |

Source-project credits list “Vlog Music Promo (Love Language)” by BombinSound on Pixabay, Kenney CC0 sound packs, and synthesized interface effects. This integration preserves the supplied mix without adding voice or replacement music.

This is a motion-graphics introduction, with illustrative positions and fixed reference prices. It is not footage of transaction signing, trading, or settlement. Four positions show a combined +1,000 USDC price effect for a −10% move; the separate formula scene shows one position contributing −1,500 USDC. Funding, fees, collateral changes, and liquidations are outside the scenario model.

There is no spoken narration. The page provides a visible description and an expandable visual story, rather than an invented speech-caption track. The existing product, pitch, and technical films retain their English captions, transcripts, downloads, and September 30 capture context.

`e2e/demo.spec.ts` checks the landing link, initial paused state, native controls, actual video decode/playback/seek, duration and dimensions, ranged download, visual-story disclosure, and viewport fit on desktop and mobile. The three narrated films keep their separate caption and transcript checks.
2 changes: 1 addition & 1 deletion docs/PWA.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Buffer on mobile and desktop

Buffer is a responsive, installable progressive web app. The same deployment serves the website, phone app, tablet app and desktop app. It does not include App Store, Play Store, Electron or native installer binaries.
Buffer is a responsive, installable progressive web app. The same deployment serves the website, phone app, tablet app and desktop app. The repository also includes an Android Web Shell project in `android/`; see [Seeker and Android setup](seeker-and-pwa.md). A generated shell is not evidence of a tested physical-device installation or an approved store release. App Store, Play Store, Electron and signed desktop distribution are not part of the web deployment.

## Install

Expand Down
Loading
Loading