TRACE

Documentation.

Start with Kestrel Detachment. It is the same desk the product uses, locked to a published pack.

  1. Ask which hops missed the intercept last week. The window is the pack as-of date minus six days.
  2. Open hop 14. The G-meter still reads 3.8 against a 2.5 limit.
  3. Play the merge radio call. Whisper marks the cue at 4.58 seconds on hop K-17. Each word has a time. The write-up still says 4:12.
  4. Ask what the scan read on the G-meter. RapidOCR admits 3.8. Then query the fuel write-ups: a read-only SELECT, write rejected.
  5. Ask for the conflicting fuel figures. 420 lb and 380 lb both stay on hop K-08. The scan admitted 420; the smudged 380 is quarantined.
  6. Ask how many hops used N999ZZ. The desk cannot answer.
  7. Open Relate. Add the starter relationship or pick two tables and keys. Read the cardinality and the orphan count.
  8. Under Ask, define a measure or add a starter. Ask for it by name: “average fuel delta by hop”. The plan names the measure it used.
  9. Pin two or three answers to a board. Copy the board receipt. Open it in a new window; every tile re-runs.
  10. Toggle “Say it plainly” on a frozen question. Accepted prose is shown. Rejected prose is struck through with the introduced token named.
  11. Switch to NTSB and ask to show the cases on a map. Coordinates stay quoted to the report.
  12. Open the FAA desk. 24,447 reported wildlife strikes in 2025. Ask what the scan read for 2025, then query 2025. Unreported events cannot be answered.
  13. On NTSB, ask what the scan read on the Hudson card, query the Hudson case, and play the spoken survival count. 155 is in the scan, the SELECT, and the transcript.

Relationship

A person names table A, key A, table B, key B. TRACE inspects both key columns. Cardinality is detected from key uniqueness on each side, never declared. Orphan keys are keys present on one side and absent on the other. The hash is over the canonical spec, so the same relationship always has the same id.

{
  "kind": "relationship",
  "relationship_id": "rel-878b23426f",
  "name": "log to fuel write-up",
  "from_table": "raw_logs",
  "from_key": "hop_id",
  "to_table": "raw_fuel",
  "to_key": "hop_id",
  "cardinality": "1:1",
  "from_rows": 24,
  "to_rows": 24,
  "matched_keys": 24,
  "orphans_from": 0,
  "orphans_to": 0,
  "orphan_from_keys": [],
  "orphan_to_keys": [],
  "duplicate_from_keys": 0,
  "duplicate_to_keys": 0,
  "hash": "878b23426fb446aa"
}

Measure

agg is one of count, sum, avg, min, max, ratio. ratio is the share of rows that match the filter. The filter grammar is column op value [and column op value …] with ops = != > >= < <=. Values are numbers or words; quotes are optional. Evaluation is a pure function of the frozen table and the measure. A question that names the measure runs it, with an optional by column group and a date window.

{
  "kind": "measure",
  "measure_id": "m-263ed8736f",
  "name": "miss rate",
  "agg": "ratio",
  "table": "hops",
  "column": "*",
  "filter": "intercept = miss",
  "clauses": [
    {
      "column": "intercept",
      "op": "=",
      "value": "miss"
    }
  ],
  "unit": "share",
  "expression": "hops where intercept = miss / hops",
  "hash": "263ed8736f40eec7"
}

Receipt and board

A receipt is a URL: pack, q, and optionally a, base64url JSON of the authored measures and relationships. A board is several questions pinned together in board. Nothing computed is stored in the URL. Opening it re-runs every ask, so the plan and the lineage on each tile are live. The board hash covers the recipe; the results hash covers the computed numbers.

/trace/demo?pack=kestrel&q=What+is+the+miss+rate+by+instructor%3F&a=eyJtZWFzdXJlcyI6W3sibmFtZSI6Im1pc3MgcmF0ZSIsImFnZyI6InJhdGlvIiwidGFibGUiOiJob3BzIiwiY29sdW1uIjoiKiIsImZpbHRlciI6ImludGVyY2VwdCA9IG1pc3MifV0sInJlbGF0aW9uc2hpcHMiOlt7ImZyb21fdGFibGUiOiJyYXdfbG9ncyIsImZyb21fa2V5IjoiaG9wX2lkIiwidG9fdGFibGUiOiJyYXdfZnVlbCIsInRvX2tleSI6ImhvcF9pZCIsIm5hbWUiOiJsb2cgdG8gZnVlbCB3cml0ZS11cCJ9XX0

/trace/demo?pack=kestrel&board=eyJzIjoidHJhY2UuYm9hcmQuMSIsInAiOiJrZXN0cmVsIiwidCI6Iktlc3RyZWwgd2VlayIsImkiOlsiV2hpY2ggaG9wcyBtaXNzZWQgdGhlIGludGVyY2VwdCBsYXN0IHdlZWs_IiwiV2hhdCBpcyB0aGUgbWlzcyByYXRlIGJ5IGluc3RydWN0b3I_Il0sImEiOnsibWVhc3VyZXMiOlt7Im5hbWUiOiJtaXNzIHJhdGUiLCJhZ2ciOiJyYXRpbyIsInRhYmxlIjoiaG9wcyIsImNvbHVtbiI6IioiLCJmaWx0ZXIiOiJpbnRlcmNlcHQgPSBtaXNzIn1dLCJyZWxhdGlvbnNoaXBzIjpbeyJmcm9tX3RhYmxlIjoicmF3X2xvZ3MiLCJmcm9tX2tleSI6ImhvcF9pZCIsInRvX3RhYmxlIjoicmF3X2Z1ZWwiLCJ0b19rZXkiOiJob3BfaWQiLCJuYW1lIjoibG9nIHRvIGZ1ZWwgd3JpdGUtdXAifV19fQ

{
  "schema": "trace.board.1",
  "pack": "kestrel",
  "title": "Kestrel week",
  "items": [{ "q": "Which hops missed the intercept last week?" }, { "q": "What is the miss rate by instructor?" }],
  "authored": { "measures": [ … ], "relationships": [ … ] }
}

Prose guard contract

Input to a model is the computed answer only: pack name, question, computed sentence, value, unit, window, id list, and source locators. The model is asked for one or two plain sentences and told to add no numbers, dates, or names. The guard extracts every number (digits, number words, spelled decimals), every date (ISO, month-day-year, partial month-day), and every identifier (hop ids, tail numbers, case ids, capitalized names) from the prose. Each must appear in the computed answer. One introduced token rejects the prose and is named in the reason. The guard is conservative: a derived count such as “two sources” is rejected because the number is not in the computed answer.

{
  "accepted": false,
  "introduced": ["21"],
  "checked": { "numbers": ["21"], "dates": [], "identifiers": ["Kestrel", "Detachment"] },
  "reason": "prose rejected: introduced 1 number not in the computed answer (21)"
}

Frozen completions live with the desk. The public desk never calls a model at request time; every accept or reject on Benchmarks is recomputed from the frozen text by the guard.

API

/api/trace/openapi.json · /api/trace/health · /api/trace/publication

Health reports the pack inventory, check counts, authored-object checks, the frozen prose tally (calls, completions, accepted, rejected, introduced-fact rate, and zero live calls at request time), and the controlled timing run. Ask runs in the browser. The publication JSON is a read of the same snapshot the desk uses. Do not upload operational records.