Initial Commit

2026-09-18 23:15:05 -04:00
commit fdcc4863f5
118 changed files with 16868 additions and 0 deletions
@@ -0,0 +1,20 @@
+# Platform evidence
+
+Checked 2026-09-18 against live official documentation. Raw working copies are in ignored `.firecrawl/`.
+
+## Convex
+
+- [Self hosting](https://docs.convex.dev/self-hosting) and [official deployment guide](https://github.com/get-convex/convex-backend/blob/main/self-hosted/README.md): backend defaults to SQLite; no PostgreSQL/Redis is necessary. Backend API uses 3210, HTTP actions 3211, dashboard 6791. Persistent `/convex/data` is essential. Generate a deployment admin key with `./generate_admin_key.sh`; CLI uses `CONVEX_SELF_HOSTED_URL` and `CONVEX_SELF_HOSTED_ADMIN_KEY`, not cloud project login. Admin key is deployment-only, never a browser environment value.
+- [Official Compose](https://github.com/get-convex/convex-backend/blob/main/self-hosted/docker/docker-compose.yml): health probe `/version`; backend SIGINT shutdown; distinct cloud/site origins. Upstream example uses `latest`; operators should pin tested image digests and back up before upgrades.
+- [Svelte quickstart](https://docs.convex.dev/quickstart/svelte), [Svelte overview](https://docs.convex.dev/client/svelte/overview): use the actual `convex-svelte` package, Svelte 5; put Convex functions in `src/convex` via `convex.json`. Root `setupConvex(url)`; declarative `useQuery(api.function, () => args)` for subscriptions. Keep domain calculations in Bun server services, not separate browser/Convex copies.
+- [Custom JWT](https://docs.convex.dev/auth/advanced/custom-jwt): supports RS256/ES256, `kid/alg/typ`, `sub/iss/exp` and client refresh `iat`. Enforce application audience. JWKS may be a data URI, avoiding a boot-time callback from Convex to the web container. This permits an EVE-login-backed application identity without handing EVE tokens to the browser. An application JWT is NOT an EVE access token.
+
+## Bun
+
+- [SQLite](https://bun.sh/docs/runtime/sqlite): synchronous `bun:sqlite` driver; parameterized prepared statements, transactions, read-only connections, strict bindings, integrity pragmas. SQLite integers are 64-bit but JS numbers only exact through 2^53−1: external EVE instance/location IDs should be decimal strings at domain boundaries. Reference type/system IDs fit safe integers and are validated.
+- Transactions must contain synchronous writes, not awaited parsing/downloads. Immutable artifact compiler can use DELETE journaling to avoid promoting a DB without a WAL sidecar. Complete/close staging file before publishing its manifest. Serving uses read-only handles to a version, not an in-place changing database.
+- Local available runtime: Bun 1.3.14. Live docs advertise a newer release; use only APIs verified by repository tests on 1.3.14 and explicitly pin the tested runtime in deployment.
+
+## Evidence caveat
+
+Documentation evolves. URLs above are live sources, not promises of permanent API compatibility. Dependency lockfile, ESI contract evidence and offline regression tests capture the implemented contract. Deployment and live-auth testing need separately configured services/credentials.