Spoke

glass-ox

AI-native Alteryx, tested by default — every data-coding step visible and proven.

Character

You code messy, inherited, multi-source HR/comp data into a canonical model — and you've been burned by a "clean" table that turned out to be quietly wrong.

Problem

External. A table you trusted was silently poisoned — a field collapsed to one value to "make progress," a 1:1 join fanned out, rows vanished with no reason code — and you didn't find out until a model regressed weeks later.

Internal. You spend 80% of the real work creating a trustworthy table, and none of it is visible or provable — you either read every count by hand or trust an AI that can't show its work.

Philosophical. Coding the data is the job; so why is the defensible labor the one part nobody can see or test?

Guide

Every transform runs through a Step that profiles its output, emits a manifest (rows in/out, join shape, drops-with-reasons, per-field coverage + concentration), and runs a fail-loud assertion catalog — conservation, cardinality, coverage, concentration, profile-before-trust, provenance — any of which halts the run. Manifests chain into a RunReport you can list, fetch, and vendor.

Abstract

Background. Inherited-and-trusted is becoming the dominant data path as AI agents are trusted to code. The default failure mode is silent — a field defaults to one value (the 84%-P3 incident), a join collapses, rows drop without a reason.

Methodology. A src/lib/glass-ox/ primitive expresses every transform as a declared-invariant Step; the spoke persists each RunReport across glass_ox tables (runs + step manifests + assertions indexed by severity + quarantines by reason) and exposes read APIs, a service-key-gated synchronous run endpoint, and MCP tools.

Scope. The spoke is the persistence + contract face of the engine — it depends on the primitive; the primitive never imports the spoke. Not a PA Instrument (workflow infrastructure).

Contribution.The assertion that the AI cannot default, invent, or silently drop to make progress is enforced mechanically — Concentration / Coverage / Conservation / Provenance halt the run. The tests are the AI's leash, not a QA afterthought.

Evidence / Provenance. Proven by replaying the CompAnalyst coding run through the harness: the black-box reclassifier step genuinely HALTs on the 84%-P3 concentration assert. Lineage: the Glass-Box Data-Workflow Standard + docs/glass-ox/CONCEPT.md.

Plan

  1. 01

    Run a registered plan

    POST /api/spokes/glass-ox/plans/companalyst-coding/run executes the bound primitive synchronously and persists the RunReport.

  2. 02

    Inspect the proof

    GET /runs/[runId] rehydrates the full step DAG — manifests, assertions, drops-by-reason; the /glass-ox canvas renders it.

  3. 03

    Find the halts

    GET /runs?overallStatus=halt (or MCP glass-ox.runs.list) surfaces every run an assertion stopped.

  4. 04

    Vendor the contract

    Consumers vendor RunReportSchema to trust a coded table without re-deriving it — trust becomes the product.

Call to Action

Direct. Run the reference plan. Watch the 84%-P3 step halt.

Transitional. Open the canvas at /glass-ox. Read the concept dossier.

Try it now

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

glass-ox.runs.list

GET

List persisted RunReport summaries — the tested data-coding runs, newest-reported-first.

curl -sS "https://people-analytics-toolbox.vercel.app/api/spokes/glass-ox/runs"

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.

// Vendor canonical types:
// src/spokes/glass-ox/contracts/types.ts

Source path: src/spokes/glass-ox/contracts/types.ts · GitHub

Try in Dev ConsoleRead the explainerThe glass-box canvas on /glass-oxBack to all spokes

Failure

A silent default, join collapse, or unexplained drop poisons a table you trusted; the failure surfaces weeks later as a "mysterious" model regression, with no manifest and no way to certify what the workflow did.

Success

Every coding step is visible and proven on its face; the silent-default class is retired because the assertions halt the run before it can produce a wrong table; and the RunReport is a vendable trust certificate.