Principia

List canonical constructs (resolved CanonicalVariable rows). Supports limit/offset, engagement_family_only, and abstraction_level (PRN-271).

Lookup one canonical construct by id (a canonical variable_id, e.g. VAR_000376). Unknown ids return found:false (soft validation).

Keyword search over construct name + definition + alternative_names + variable_codes. Argument is `q` (not `query`).

Resolve a source-side construct {name, definition?, variable_code?} against the canonical store. READ-ONLY — does not mutate. Uses meta-factory's matcher ([email protected] / [email protected] / [email protected]).

List InstrumentCard rows. Optional construct_id filter narrows to instruments covering a given construct.

Lookup one instrument by instrument_id. Unknown ids return found:false.

Keyword search over instrument_name + developer + constructs_covered.

Lookup one survey item by item_id. SPEC §6/Q4 enforced: items_license != public_domain|open returns status:'restricted'.

Search items by text. Restricted items (proprietary instruments) are returned with text fields stripped; restricted_count surfaces how many.

Lookup one citation by id OR doi. Scans both id-keyed and doi-keyed candidates.

Keyword search over title + apa_reference + doi + authors.

List Measure rows. entity_kind filter selects scientific_construct vs operational_metric.

Lookup one Measure by measure_id. Unknown ids return found:false.

Return instruments that measure a given construct, ranked by composite score (reliability + validity + literature usage + recency). Optional filters: min_reliability, cross_cultural_only, length_lte. Read-only — no mutation (curator-policy D4).

List Model rows (theoretical / structural frameworks).

Lookup one Model by model_id. Unknown ids return found:false.

Keyword search over model_name + description.

Search EffectSize rows by from/to/statistic_type. Each returned value's observed/corrected basis is named per EFFECT_ESTIMATE_GLOSSARY (@people-analyst/measurement-core) — PRN-N1013-M4; a row with no typed estimates block reads 'basis not recorded', never a bare statistic symbol.

Return Evidence[] edges that name a given entity_id as the claim subject.

Search owned, OA-sourced, attributed, stance-classified evidence quotes for a construct→construct relationship (from/to), or any statement naming a single construct. Filters: stance, displayable_only. The display layer for the metric profile page + book.

Lookup a synthesized Bayesian prior by id OR (from_construct_id, predicate, to_construct_id). Empty until PRN-021 synthesis engine ships. PRN-N1013-M4: a prior's r pools observed and corrected contributing effects without a per-row marker yet (EFFECT_ESTIMATE_GLOSSARY.units_not_recorded, @people-analyst/measurement-core) — read it as basis-not-recorded, not as raw r.

Search canonical priors by from/predicate/to. Empty until PRN-021 synthesis engine ships.

List canonical theoretical models (JD-R, COR, SDT, AET, JCM, Goal-Setting, Equity, Two-Factor, etc.). Sorted by foundational publication year. Read-only.

Look up one CanonicalTheoreticalModel by id (e.g., theory.jd_r). Returns the theory's canonical constructs, canonical relations (with predicates), descendant per-study models, and foundational citations.

Search theoretical models by keyword over name/summary/constructs. Optional filters: invokes_construct_id (theories that invoke a specific construct), field_domain (classification axis).

Look up InstrumentEquivalence rows by `id` OR by the canonical tuple (`construct_id` + `instrument_a` + `instrument_b` [+ optional `mapping_method`]). Pair ordering is normalized server-side so (Q12, UWES-9) and (UWES-9, Q12) resolve to the same row. Returns `{matches, total, note?}` — array-shaped because a (construct, pair) can carry multiple methods.

Search InstrumentEquivalence rows by `construct_id` and/or `instrument_id`. `instrument_id` matches either side of the pair. Optional `mapping_method` filter.

Look up one MethodologyCritique by `critique_id`. Returns `{matches, total, note?}` — array-shaped for parity with equivalences. Matches list contains 0 or 1 element.

Search MethodologyCritique rows by composite filter (`subject_id`, `subject_type`, `critique_type`, `severity`). All filters AND together; any subset of the four is valid. Read-only (curator-policy D4).

List CanonicalSurveyItem rows (PRN-050 item-level dedup spine). Each row aggregates one normalized item stem across N source instruments via source_items[].

Lookup one CanonicalSurveyItem by canonical_item_id (e.g., CITM_7350938cb42d). Unknown ids return found:false.

Keyword search over normalized_text + alternative_texts. Optional instrument_id filter narrows to canonical items whose source_items[] reference that instrument.

Retrieve the full causal chain from a construct, condition, or problem to interventions, with evidence grades at each hop. problem_id accepts pf.* addresses from the problemframe-2026-v1 frozen registry (cert d0770859) and resolves construct mappings via the MF-711 pf→construct join (landed 2026-09-11); an address with no join coverage yet resolves the problem frame with an honestly empty linked_constructs[], not an error. condition_id accepts bicycle-guide's minted cond_<slug> ConditionFrame ids and resolves via the PRN-281 crosswalk (landed 2026-09-11); a condition with no construct match yet resolves honestly empty the same way. All three entry points are fully resolved today — no path is gated.

Look up one Intervention by `intervention_id`. Returns `{matches, total, note?}` — array-shaped for parity with critiques + equivalences. Matches list contains 0 or 1 element.

Search Intervention rows by composite filter (`construct_id` — matches when `targets_constructs[]` includes the id; `problem_id` — a ProblemFrame pf.* address, resolved via the MF-711 pf→construct join to one or more construct ids and then matched the same way as `construct_id`; `modality` — matches when `delivery_modality[]` includes the modality; `cost_band` — exact match on `typical_cost_band`). All filters AND together; any subset is valid. Read-only (curator-policy D4).