Skip to content
Docs Central

02 Product Capability Contract

Product Capability Contract

Section titled “Product Capability Contract”

Status: SHARP. Product promise, boundaries, acceptance scenarios, and parity standard are decided. Denoising state: sharp (noise -> rough -> sharp -> converged) Updated: 2026-07-23

Purpose

Section titled “Purpose”

Define what bioloupe-data must let a consumer understand when it is complete. This is the durable product contract. It describes capabilities and observable outcomes, not an implementation roadmap or a copy of the legacy schema.

The Product in One Sentence

Section titled “The Product in One Sentence”

bioloupe-data turns fragmented pharmaceutical source evidence into a connected, time-aware, explainable SQL knowledge product.

It should answer seven questions cleanly:

  1. What is this thing?
  2. What is being developed, for whom, and in what context?
  3. How far has it progressed, and what is happening now?
  4. What evidence supports that interpretation?
  5. Who sponsors, owns, or controls it, and when?
  6. What changed over time?
  7. Can I inspect why every important answer was published?

Product Shape

Section titled “Product Shape”
flowchart LR
  Sources["Primary sources"]
  Artifacts["Immutable artifacts"]
  Evidence["Source-grounded evidence"]
  Identity["Resolved identities"]
  Canonical["Canonical facts and state"]
  Synthesis["Programs, landscapes, summaries"]
  Query["Stable q_* SQL models"]
  Consumers["Aero and read-only agents"]

  Sources --> Artifacts --> Evidence --> Identity --> Canonical --> Synthesis --> Query --> Consumers
  Canonical --> Query

The graph has one direction. Source and canonical assets never depend on q_*; query models are the terminal consumer contract. Cross-slice synthesis consumes canonical assets and publishes its own canonical facts or query projections.

Capability Scenarios

Section titled “Capability Scenarios”

Completion is judged by these user scenarios. A scenario passes only when its answer is source-backed, identity-resolved, queryable through stable SQL, and explainable through q_provenance.

IDConsumer questionRequired product outcomePrimary owner
P01What entity does this name or identifier refer to?Resolve drugs, brands, regimens, diseases, biomarkers, organisations, targets, technologies, endpoints, and adverse events without silently merging ambiguity.29-32, 26
P02Give me the complete profile of this drug.Identity, aliases, brands, targets, technologies, approvals, trials, development programs, evidence, commercial observations, ownership, and recent events join through stable keys.29, 22, 33, 35
P03Give me the complete profile of this disease.Taxonomy, biomarkers, epidemiology, standard of care, approved therapies, active and historical development programs, trials, evidence, and news are available at explicit grains.30, 25, 34, 33
P04What is the development landscape for this disease, target, technology, company, or treatment line?Query current activity separately from historical maximum phase and regulatory state; drill into the programs and evidence behind every count.33
P05What does this clinical trial say?Protocol, eligibility, interventions, endpoints, sites, sponsors, status history, structured results, safety, publications, and provenance are available without flattening incompatible grains.21
P06What new clinical evidence has emerged?Compare source-specific efficacy and safety observations by program, disease context, arm, population, endpoint, timepoint, and source type without inventing a merged truth.23, 21, 33
P07What is approved and what is standard of care?Keep regulator decisions, label evidence, guideline recommendations, observed practice, and reviewed promotions distinct; a label-approved use must never auto-publish as SOC.22, 25
P08What does this organisation own, sponsor, sell, or partner on?Resolve temporal ownership, sponsorship, collaborations, deals, filings, development programs, marketed products, and reported sales.26, 33, 35
P09What is the disease burden?Query incidence, prevalence, mortality, survival, and related observations with geography, population, period, denominator, method, and source intact.34
P10What is the commercial record of this product?Query source-reported product sales and regulatory exclusivity context without mixing periods, currencies, geographies, or forecasts.35, 22
P11What changed, and what did we know at a given time?Inspect source observations, milestones, effective intervals, supersession, and current state with observed/effective time kept distinct.all slices; 33 for programs
P12Find and explain the best evidence for this question.Search/filter across published models, inspect catalog semantics, and traverse every returned fact to its evidence and acceptance receipts.27, 07

make verify-bootstrap now executes one checked-in, read-only SQL proof for every scenario after the entire fixture graph and all asset checks build from a blank database. These are representative contract proofs, not production-volume claims: source breadth, consumer cutover, and shadow comparison remain separate completion conditions below. Fixture proof is governed by ADR-0012.

Capability Map

Section titled “Capability Map”
Capability familyOwning specCore SQL surfaces
Clinical trials21-slice-clinical-trials.mdq_trials, interventions, endpoints, eligibility, sites, sponsors, results, safety
Regulatory approvals22-slice-regulatory-approvals.mdapprovals, indications, labels, regulatory product and exclusivity facts
Publications and conferences23-slice-publications.mdpublications, trial links, outcomes, safety evidence
News and intelligence24-slice-news-intelligence.mdsource articles, entity mentions, typed events
Standard of care25-slice-standard-of-care.mdrecommendations, treatment approaches, evidence
Organisation intelligence26-slice-organisation-intelligence.mdorganisations, temporal relationships, ownership, deals, filings
Discovery and search27-slice-discovery-search.mdSQL-native facets, text retrieval, evidence-bearing search results
Forecasting and TPP support28-slice-forecasting-tpp.mdoptional input-readiness models; no forecast engine
Identity spines29-32drugs, diseases, biomarkers, targets, technologies, endpoints, adverse events
Development programs and landscapes33-slice-development-landscapes.mdprograms, state history, milestones, program evidence, emerging clinical evidence
Epidemiology34-slice-epidemiology.mdobservations, comparable series, selected disease summaries
Commercial intelligence35-slice-commercial-intelligence.mdreported product sales and commercial summaries
Catalog and explanation07-sql-query-layer.mdq_catalog, q_provenance, fact-path contracts

What Intent-Faithful Parity Means

Section titled “What Intent-Faithful Parity Means”

Data Gov parity is scenario parity, not table, route, model, task, or screen parity.

A legacy capability is preserved when:

  1. its real user question is represented by a scenario above;
  2. the greenfield source authority is explicit;
  3. the domain grain and identity owner are explicit;
  4. the answer is available through stable q_* SQL;
  5. source and decision provenance can explain it;
  6. Aero or another named consumer can switch without querying legacy physical tables;
  7. legacy-only machinery can be deleted after a measured shadow period.

The following are not evidence of parity by themselves:

  • matching Data Gov’s 200-plus table count;
  • recreating Rails models, Scenic views, Thor workflows, or ActiveAdmin resources;
  • reproducing an accidental column or ranking formula;
  • returning a similarly shaped JSON payload;
  • loading legacy output directly as canonical truth.

Product Boundaries

Section titled “Product Boundaries”

bioloupe-data owns facts, identities, evidence, curation overlays, temporal interpretations, and stable SQL read models.

It does not own:

  • REST, GraphQL, serializers, or an application server;
  • authentication, authorization UI, saved searches, or user preferences;
  • Aero page composition or presentation state;
  • forecasting engines, scenarios, saved models, or revenue projections;
  • narrative report generation;
  • hidden human review columns or mutable administrative truth;
  • a second knowledge graph reconstructed inside a consumer.

Design Corrections Recovered from Data Gov

Section titled “Design Corrections Recovered from Data Gov”
Legacy shapeProduct intentGreenfield correction
drug_status, phase, approval, and active/inactive trial logic collapsed into ranking viewsshow where a therapeutic program is now and how far it ever progressedmodel contextual development programs; keep clinical activity, clinical phase, historical maximum, and regulatory state separate (33, ADR 0008)
parallel “current” and “all trials” views with subtly different filterssupport present-state and historical analysispublish explicit current state, temporal state history, and milestones from one derivation contract
missing treatment line sometimes defaulted to first linelet users filter by known line without losing unknownspreserve unknown as null; never turn absence into 1L
approval treated as a phase above Phase 4rank commercial maturitykeep regulatory state orthogonal to clinical phase
disease statistics reduced to a selected value or display stringunderstand disease burden and feed downstream analysispreserve metric, geography, population, denominator, period, method, unit, and source (34)
product sales reduced to a few annual/quarterly USD columnsunderstand reported commercial performancepreserve reporting period, geography, currency, fiscal basis, restatements, and conversion receipts (35)
publication and registry results blended into convenient report rowsfind emerging clinical evidenceexpose source-specific observations at arm/population/endpoint grain and make selection explicit (33)
API and UI shapes became de facto data contractsprovide stable consumer accesspublish versioned SQL contracts only (07)

Legacy evidence comes from ../bioloupe-data-gov/README.md, docs/, config/routes.rb, db/views/, app/workflows/, and the current Aero entity registry at ../bioloupe-aero/apps/studio-server/src/entities/registry.ts. Those artifacts establish product intent; they do not establish the greenfield architecture.

Completion Contract

Section titled “Completion Contract”

The replacement is complete only when all of the following are true:

  • every scenario P01-P12 has an automated representative acceptance slice;
  • every published noun and key has one owning doc and one implementation owner;
  • every required source has immutable capture, replay, and freshness behavior;
  • every live source path has separate bounded-smoke and complete-bootstrap evidence; fixture success is never counted as live parity;
  • every high-impact fact has source, extraction, resolution, acceptance, and optional curation receipts;
  • all identity references pass owner-spine referential integrity checks;
  • current and historical state can be reproduced without hidden date-window heuristics;
  • q_catalog describes every published column, grain, owner, closed enum, and provenance policy;
  • q_provenance explains every provenance-required row or fact;
  • Aero reads only q_* models for migrated capabilities;
  • shadow comparisons meet declared coverage and correctness thresholds;
  • the legacy read path can be disabled, observed, and removed without losing a required scenario.

This contract is intentionally stricter than “the pipeline ran.” A successful materialization with incomplete semantics, provenance, or consumer coverage is not completion.

References

Section titled “References”