# M0 · Foundations (T00–T04)

Exit gate: `pnpm dev` starts web, admin, api and workers locally against Docker Postgres + Redis; migrations apply; CI is green.

---

## T00 · Monorepo scaffold

**Goal** A pnpm + Turborepo monorepo with all apps and packages as empty, compiling shells, plus CI.

**Depends on** none

**Read first** `annexe-mise-en-place.md`, `build-conventions.md`, `CLAUDE.template.md`

**Build**
- root: `package.json`, `pnpm-workspace.yaml`, `turbo.json`, `tsconfig.base.json`, `.eslintrc.cjs`, `.prettierrc`, `.editorconfig`, `.gitignore`, `.env.example`, `.nvmrc` (22)
- `apps/{web,admin,api,workers}`, `packages/{config,db,core,chain,agents,templates,ui}` each with `package.json`, `tsconfig.json`, `src/index.ts`
- `infra/docker-compose.yml` (postgres:16, redis:7, with healthchecks and named volumes)
- `.github/workflows/ci.yml`

**Steps**
1. Create the workspace and Turborepo pipelines: `build`, `dev`, `lint`, `typecheck`, `test` (with correct `dependsOn`).
2. `apps/web` and `apps/admin`: `create-next-app` equivalent (App Router, TS, Tailwind, no src dir alias conflicts). `apps/api`: Fastify hello on `:4000` with `GET /v1/health → { ok: true }`. `apps/workers`: a process that connects to Redis and logs "workers ready".
3. `packages/config`: `loadEnv()` validating every variable of annexe F with zod; export a typed `env`. Missing required var = crash at boot with the var name.
4. `.env.example`: every variable from annexe F, empty values, grouped with comments.
5. ESLint (typescript-eslint strict), Prettier, Vitest at root with a sample test per package.
6. CI: install, lint, typecheck, test, `forge build` placeholder step skipped until T30, gitleaks secret scan.

**Done when**
- [ ] `docker compose -f infra/docker-compose.yml up -d` → both healthy
- [ ] `pnpm i && pnpm build` succeeds from a clean clone
- [ ] `pnpm dev` serves web :3000, admin :3001, api :4000 (`curl :4000/v1/health` → `{"ok":true}`), workers log "workers ready"
- [ ] `pnpm lint && pnpm typecheck && pnpm test` pass
- [ ] Removing `DATABASE_URL` from `.env` makes `pnpm dev` fail with a clear message
- [ ] CI runs on a PR and is green

**Out of scope** Any business logic, DB schema, UI design.

---

## T01 · Database schema, migrations, seed

**Goal** The full Postgres schema of annexe A in Drizzle, migrated, with an example seed.

**Depends on** T00

**Read first** `annexe-base-de-donnees.md` (all of it), `analyse-des-projets.md` (token lifecycle), `annexe-score-de-reprise.md` (recovery_scores.components)

**Build** `packages/db/src/schema/{enums,tokens,users,cycles,operations,treasury,admin}.ts`, `packages/db/src/client.ts`, `packages/db/drizzle.config.ts`, `packages/db/migrations/*`, `packages/db/src/seed.ts`, root scripts `db:generate`, `db:migrate`, `db:seed`

**Steps**
1. Translate every `create type` and `create table` of annexe A to Drizzle 1:1 (names, nullability, defaults, uniques, indexes, FKs). `numeric(78,0)` → `numeric({ precision: 78, scale: 0, mode: 'bigint' })` via a custom type that returns `bigint`.
2. Add `check` constraints: EVM address regex, `score between 0 and 100`, `position between 1 and 5`, `vote_closes_at > vote_opens_at`.
3. Export typed `db` client (node-postgres pool) and inferred row types.
4. Seed (`example` data only, clearly named): 5 validated example tokens (KEEL, PULSR, NODA, ORBI, WEFT with the values from the dapp mockups), 1 published cycle, 1 operation in progress (GRIDL), the 6 `wallets` rows with placeholder addresses, default `settings` rows (all thresholds from `analyse-des-projets.md` and annexe E).
5. Add a `resetTestDb()` helper for integration tests.

**Done when**
- [ ] `pnpm db:migrate` on an empty DB succeeds; `pnpm db:generate` produces no diff afterwards
- [ ] `pnpm db:seed` runs twice without error (idempotent upserts)
- [ ] Test: inserting a vote twice for the same (cycle, user) fails with a unique violation
- [ ] Test: inserting a token with an invalid address fails the check constraint
- [ ] Test: a `numeric(78,0)` column round-trips `2n ** 200n` exactly

**Out of scope** Business rules in code (they live in packages/core).

---

## T02 · Chain package

**Goal** `@vivra/chain` gives typed read clients, chunked log fetching and a guarded write path for testnet / fork / mainnet.

**Depends on** T00

**Read first** `annexe-contrats.md`, `token-vivra-et-tresorerie.md`, `cto-pons-et-frais.md`

**Build** `packages/chain/src/{config.ts,clients.ts,logs.ts,write.ts,errors.ts}`, `packages/chain/src/abi/` (placeholders + README)

**Steps**
1. `config.ts`: per `CHAIN_ENV` → chain id (4663 mainnet, 46630 testnet), RPC + fallback, Pons factory/escrow/hook addresses (from annexe D), burn address, BuybackBurner address (env).
2. `clients.ts`: viem `publicClient` with fallback transport (primary then fallback RPC, 2 retries); `walletClient(keyRef)` that loads a private key from the secrets manager adapter (interface `SecretStore.get(ref)`; local dev implementation reads from env var named by the ref).
3. `logs.ts`: `getLogsChunked({ address, event, fromBlock, toBlock, chunk=10_000 })` that splits ranges, retries on "range too large" by halving, returns logs in order.
4. `write.ts`: `sendTx({ request, capCheck, ledger })`: refuse if `CHAIN_ENV !== 'mainnet'` and chain id is mainnet; `simulateContract`; run `capCheck()`; send; wait 1 confirmation; call `ledger(txHash, receipt)`; return hash. Idempotency key param: if a ledger row with that key has a tx_hash, return it without sending.
5. `abi/`: put a README listing the ABIs needed (Pons factory v2, escrow, Meme hook, curve, ERC-20) and an `erc20.json`. Pons ABIs are fetched from the explorer in T10 (⚠️ Pons).

**Done when**
- [ ] Unit test: `getLogsChunked` splits 0→25,000 into 3 calls with chunk 10,000, and halves on a mocked "range too large" error
- [ ] Unit test: `sendTx` on a mocked mainnet chain with `CHAIN_ENV=testnet` throws `WRONG_CHAIN_ENV` and never sends
- [ ] Unit test: `sendTx` with an existing idempotency key returns the stored hash and never sends
- [ ] Testnet smoke (`TESTNET=1 pnpm --filter @vivra/chain test`): reads latest block number on chain 46630

**Out of scope** Pons-specific reads (T10), BuybackBurner (T30).

---

## T03 · API skeleton

**Goal** Fastify app with config, logging, error format, rate limiting, CORS, sessions plumbing and a WebSocket hub.

**Depends on** T00, T01

**Read first** `annexe-api.md` (Généralités, format d'erreur, limites), `build-conventions.md` (API)

**Build** `apps/api/src/{server.ts,errors.ts,plugins/{db,session,rateLimit,cors,ws}.ts,routes/health.ts}`

**Steps**
1. `ApiError` + global error handler producing `{ error: { code, message } }`; zod validation errors → `invalid_input` 400; unknown → `internal` 500 with `request_id`.
2. pino logger with `request_id`; redact `cookie`, `authorization`, `email`, `code`.
3. CORS limited to `APP_URL` and admin URL. Rate limits per annexe B (per route config).
4. Session plugin: reads `vivra_session`, loads `sessions` row (not revoked, not expired), sets `req.user`. Helper `requireUser()`.
5. WebSocket hub at `/v1/ws`: clients send `{ subscribe: "cycle:<id>" | "operation:<id>", since?: number }`; server keeps rooms; `publish(room, message)` exported for other modules; ping every 25s. Use Redis pub/sub so workers can publish.

**Done when**
- [ ] Test: unknown route → 404 `{ error: { code: "not_found" } }`
- [ ] Test: bad body → 400 `invalid_input` with the field name in `message`
- [ ] Test: 121 requests/min on a public route → 429 with `Retry-After`
- [ ] Test: a message published on Redis channel `ws:operation:1` reaches a WS client subscribed to `operation:1`
- [ ] Logs never contain the string of a cookie value (test with a fake cookie)

**Out of scope** Auth flows (T40), domain routes.

---

## T04 · Workers skeleton

**Goal** BullMQ worker process with every queue of annexe F registered, a scheduler for repeatable jobs, idempotency and alert helpers.

**Depends on** T00, T01

**Read first** `annexe-mise-en-place.md` (Files et tâches planifiées), `securite-et-observabilite.md` (alertes)

**Build** `apps/workers/src/{index.ts,scheduler.ts,queues.ts,lib/{idempotent.ts,alert.ts,lock.ts}}`, one stub job file per queue

**Steps**
1. Register queues: `projects.analyze`, `tracking.candidates`, `tracking.live`, `tracking.followup`, `cycles.clock`, `orchestrator.tick`, `agents.run`, `tg.updates`, `buyback.slices`, `buyback.refill`, `treasury.daily`, `social.publish`, `alerts.check`.
2. Repeatables: every minute for `cycles.clock`, `orchestrator.tick`, `social.publish`, `alerts.check`; every 15 min `tracking.candidates`; hourly `tracking.followup`; daily 00:30 UTC `treasury.daily`; daily `buyback.refill`.
3. `idempotent(jobKey, fn)`: Postgres advisory lock + a `job_runs` table (add it to packages/db in this ticket) storing key, status, result.
4. Retry policy from conventions. On final failure: `alert({ level, message, context })` → Telegram team chat (`TELEGRAM_ALERTS_CHAT_ID`) and pino.
5. Graceful shutdown on SIGTERM (finish current jobs, 30s max).

**Done when**
- [ ] `pnpm --filter workers dev` logs every queue name once at boot
- [ ] Test: running the same `idempotent('x', fn)` twice concurrently executes `fn` once
- [ ] Test: a job that throws 3 times calls `alert` once with the job name
- [ ] SIGTERM during a 5s fake job lets it finish, then exits 0

**Out of scope** Real job logic (later tickets fill each stub).