Fuente: ddx-documentation/adr/0024-card-folders.md
- **Status:** Accepted (plan `osprey-card-folders`). - **Refines:** [ADR 0022](/es/docs/adr/0022-ibis-pack-reuse) (pack import) and [ADR 0023](/es/docs/adr/0023-dx-assistant) (PENDING-only self-curation). - **Plan:** `plans/osprey-card-folders/` (`00-design.md` holds the format and the health-code table). - **Docs:** `ddx-osprey-engine/CLAUDE.md` (CLI, routes, tables, suite `dx-card-folders`). ## Context Diagnosis cards came from imported packs (ADR 0022) with AI-authored, unverified evidence and no media. Five must-not-miss cards need reviewed, cited, versioned content with licensed media, a repair loop, and a way back from a bad version. ## Decision 1. **Format `osprey-dx-card/1` (D2).** One folder per card under `ddx-osprey-engine/datasets/diagnosis/cards/<CODE>/`: `card.json` (schema `DxCardFolderSchema`, `@ddx/contracts/osprey-diagnosis-card-folder`) + `media/<file>` (sha256, size and mime verified on read, ≤ 2 MiB each). `osprey dx cards install` extends the pack seam (`pack-install.ts` idempotency + `publishRevisionTx`) and is the operator review act for folder seeds; no route installs. 2. **Media bytes live in the engine blob store (D1).** `osprey.blob` (sql/012 precedent) + `dx_card_media` (sql/024); served engine → ddx-api byte proxy (`GET /osprey/diagnosis/cards/:cardId/media/:mediaKey`) → BFF. No presigned URL (ADR 0011 stays). The install is an engine CLI act with no upload path to ddx-api, which rules out a ddx-api store. 3. **Versioning.** A folder version must exceed the installed head unless its content hash equals it (same hash = no-op, same version + other hash = refused). Curation publishes minor bumps, so the next folder version is above the last curated one. Rollback (`dx cards rollback <code> --to <semver>`) publishes a NEW revision with the target's content (revisions are immutable); the old head becomes `superseded`, nothing is deleted. 4. **Self-heal rides the miners job (D3).** The `healCards` step runs `checkCards`, stores one `dx_curator_job` row per card (kind `heal`, report jsonb) and sends repair candidates to `curateCards` only while `curatorEnabled`. No new setting, no new scheduler job. Errors in folder content (`missing_label`, `dangling_ref`, `media_mismatch`, `evidence_no_url`) are the folder author's fix; warnings go to a curator run. 5. **Curation never publishes.** `POST /diagnosis/cards/curate` (platform super-admin) only produces PENDING proposals (`proposed_by system:curator`); a reviewer `decide()` publishes, reviewer ≠ proposer, behind the promotion gate. The route answers at once; collecting finished curator runs happens in the background. 6. **Labels are resolved engine-side (D4).** `GET /diagnosis/runs/:id/labels` returns `{locale, labels}` for every id a run's outputs name; the `/outputs` array shape stays and the web never labels ids itself. The usage harness (`ddx-osprey-usage`, `./ddx-manage.sh usage`) reuses ddx-seeder `bearerFor` through a package exports map (D5) and approves a proposal only with `--approve` (D6); the default flow stops at pending proposals. ## Consequences - A card is reviewable as a git diff of one folder; media hashes make a swapped file fail the install. - Reading existing data is never blocked: `dx cards check` reports, it does not gate runs. - Hand-written folder content is the only source of `2.0.0`; AI research enters only as PENDING proposals. ## Update (2026-11-13) The decisions above stand. Two facts changed after this ADR (plan `dx-card-kb`): - A card author now writes card folders. It lives in `ddx-osprey-engine/src/diagnosis/card-author/` and runs from `dx cards author` or `POST /diagnosis/card-author/runs`. It never installs: the folder is stored on the run row, and a reviewer submits it as a PENDING proposal. - A proposal has a `kind`: `diff` or `folder`. A `folder` proposal publishes through `installCardFolder` in `decide()` (`curation/proposals.ts`), under the same rule: reviewer is never the proposer. Decision 5 still holds. ## Rejected alternatives - **Presigned MinIO URLs for media.** Rejected: ADR 0011 keeps the browser off storage; the ddx-api byte proxy already exists. - **A separate self-heal scheduler job + setting.** Rejected: the miners job already runs on the schedule and window claim.
osprey-card-folders).plans/osprey-card-folders/ (00-design.md holds the format and the health-code table).ddx-osprey-engine/CLAUDE.md (CLI, routes, tables, suite dx-card-folders).Diagnosis cards came from imported packs (ADR 0022) with AI-authored, unverified evidence and no media. Five must-not-miss cards need reviewed, cited, versioned content with licensed media, a repair loop, and a way back from a bad version.
osprey-dx-card/1 (D2). One folder per card under ddx-osprey-engine/datasets/diagnosis/cards/<CODE>/:
card.json (schema DxCardFolderSchema, @ddx/contracts/osprey-diagnosis-card-folder) + media/<file>
(sha256, size and mime verified on read, ≤ 2 MiB each). osprey dx cards install extends the pack seam
(pack-install.ts idempotency + publishRevisionTx) and is the operator review act for folder seeds; no route installs.osprey.blob (sql/012 precedent) + dx_card_media (sql/024);
served engine → ddx-api byte proxy (GET /osprey/diagnosis/cards/:cardId/media/:mediaKey) → BFF. No presigned URL
(ADR 0011 stays). The install is an engine CLI act with no upload path to ddx-api, which rules out a ddx-api store.dx cards rollback <code> --to <semver>) publishes a NEW revision with the target's
content (revisions are immutable); the old head becomes superseded, nothing is deleted.healCards step runs checkCards, stores one dx_curator_job row per
card (kind heal, report jsonb) and sends repair candidates to curateCards only while curatorEnabled. No new
setting, no new scheduler job. Errors in folder content (missing_label, dangling_ref, media_mismatch,
evidence_no_url) are the folder author's fix; warnings go to a curator run.POST /diagnosis/cards/curate (platform super-admin) only produces PENDING proposals
(proposed_by system:curator); a reviewer decide() publishes, reviewer ≠ proposer, behind the promotion gate. The
route answers at once; collecting finished curator runs happens in the background.GET /diagnosis/runs/:id/labels returns {locale, labels} for every id a
run's outputs name; the /outputs array shape stays and the web never labels ids itself.The usage harness (ddx-osprey-usage, ./ddx-manage.sh usage) reuses ddx-seeder bearerFor through a package exports
map (D5) and approves a proposal only with --approve (D6); the default flow stops at pending proposals.
dx cards check reports, it does not gate runs.2.0.0; AI research enters only as PENDING proposals.The decisions above stand. Two facts changed after this ADR (plan dx-card-kb):
ddx-osprey-engine/src/diagnosis/card-author/ and runs from
dx cards author or POST /diagnosis/card-author/runs. It never installs: the folder is stored on the run row,
and a reviewer submits it as a PENDING proposal.kind: diff or folder. A folder proposal publishes through installCardFolder in decide()
(curation/proposals.ts), under the same rule: reviewer is never the proposer. Decision 5 still holds.adr/
deploy/
research/