Spoke

principia-connector

Reserved bridge toward Principia canonical measurement corpus — cache plus MCP (TB-PRINCIPIA-04).

Character

You need constructs, citations, instruments, items, and effect sizes flowing into People Analytics substrates without copy-pasting DOIs into Slack threads.

Problem

External. Academic measurement artefacts live outside HR stacks; hallucinating construct ids erodes reproducibility between teams.

Internal. You babysit brittle CSV crosswalks every time Principia publishes construct splits or redirects canonical variables.

Philosophical. Principia-backed constructs deserve the same connector discipline as Census, NAICS, and O*NET feeds.

Guide

TODAY: heartbeat + scaffolding only—the registry deliberately marks coming-soon while Principia MCP (PRN-014) ripens. Tomorrow: typed cache layers, MCP discovery/read tools (principia.constructs.*, citations, instruments, effects), TTL policies, webhook cache bust, audits mirroring MCP expectations, explicit resolver-redirect semantics warning rather than throwing when CanonicalVariables bifurcate. principia-connector is the governed read-mostly window—not a surrogate for Principia curation consoles.

Abstract

Background. Toolbox catalogs already unify analyses, viz, data sources—but measurement-theory artefacts require Principia interoperability to close the evidentiary gap for psychometrics and segmentation psychology rows awaiting construct ids.

Methodology. TB-PRINCIPIA-04 will vendor @measurement/core contracts locally; persist TTL-governed caches for constructs/instruments/items/citations/effects; register MCP tools mirroring Principia MCP capabilities; annotate audits per invocation aligning with scholarly provenance expectations; surface integration status upward into PAT data-source catalog conventions.

Scope. Explicitly coming-soon: only GET …/health proves namespace wiring; authoring stays inside Principia admin experiences not this spoke.

Contribution. When live, aligns calculus softness around metric semantics, segmentation psychological segments, reincarnation studies with peer-reviewed citations without brittle manual dedupe.

Evidence / Provenance. README cites toolbox vision overlap plus Principia SPEC / handoffs (TB-PRINCIPIA obligation list).

Plan

  1. 01

    Track Principia MCP readiness

    Subscribe to PRN-014 release notes signalling upstream MCP invocability powering TB-PRINCIPIA-04.

  2. 02

    Stage cache migrations

    Land Postgres tables + ingestion jobs once Principia emits stable contract payloads for snapshotting TTL windows.

  3. 03

    Register MCP + HTTP wrappers

    Mirror discovery flows from Principia MCP with identical Zod payloads + audit taps per toolbox PAT-33 expectations.

  4. 04

    Wire integration catalog

    Flip PAT-45 integration status indicators when caches achieve connected posture with evidenced freshness SLA.

Call to Action

Direct. Inspect GET /api/spokes/principia-connector/health acknowledging namespace scaffolding only today.

Transitional. Read TB-PRINCIPIA obligation checklist inside README for upcoming obligations.

Spoke I/O (visual language v1)

Every toolbox spoke shares the same abstract choreography: typed inputs on the left, distilled verbs in the center, typed outputs on the right, and (when relevant) cross-spoke HTTP composition along the bottom rail. Source package: @people-analytics-toolbox/spoke-illustrations.

Principia connectorINPUTSMAIN ACTIONSOUTPUTSConstruct hypothesis queriesEvidenceQueryPackBridge Principia corpusPackage cites + vocab stubsCitation bundlesReferencePackageMeasurement vocab (GA soon)OperationalDefDraft↳ see SURFACE §1 caveatCOMPOSES WITHprincipia

Try it now

Copy this curl. Paste in any terminal. Public read — no auth needed.

principia-connector.health

GET

Only live route until PRN-014 + TB-PRINCIPIA-04 complete the cache + MCP tool surface.

curl -sS "https://people-analytics-toolbox.vercel.app/api/spokes/principia-connector/health"

Vendor the contract

The Zod contract is the source of truth. Vendor a copy into your consumer app — you keep it; we don't break it underneath you. Re-vendor when the version bumps.

// CONTRACT_VERSION pinned at 0.0.0 until TB-PRINCIPIA-04 vendors real types:
// src/spokes/principia-connector/contracts/types.ts

Source path: src/spokes/principia-connector/contracts/types.ts · GitHub

Try in Dev ConsoleRead the explainerRegistry shows coming-soon postureBack to all spokes

Failure

Construct ids fork silently between teams—as academic literature diverges, People Analytics cites stale operationalisations unknowingly jeopardising reputational audits.

Success

Once live every agent call referencing constructs carries citation-grade provenance, redirect warnings on canonical churn, TTL transparency for compliance briefings.