Data Provider

data-provider

Parallax proposes an ontology from what is actually in a context, and refuses to run until a human accepts it. That makes every answer a function of what reached the proposer — and business-data, its richest ingress, has no supplier. Today a person types the table list by hand. This is the layer that fills it.

The searching is yours. This skill owns the four things that must be the same every time and checkable afterwards.

The split, and why it is the point

A model that both gathers evidence and decides whether the evidence is good is grading its own homework. A model that gathers, and a function that grades against a stated rule, is not. That is the entire architecture.

The flow

# 1. Search however you like. For each thing you read and intend to cite,
#    save what you actually read -- not just the URL.
#
# 2. Build a records file: one object per row, one key per column.
#    A field is EITHER read from an artifact OR inferred. Never neither.
cat > records.json <<'JSON'
[
  {
    "company": {"value": "Arepas del Valle",
                "evidence": {"url": "https://…/directory/1",
                             "sha256": "…", "snapshot": "evidence/….snapshot"}},
    "fit":     {"value": 0.82, "inferred_from": "category match against the brief"}
  }
]
JSON

# 3. Emit. By default this OPENS every cited artifact and checks its digest
#    before classifying anything observed -- an unchecked citation is not
#    evidence, and `--unverified` exists only so that skipping the check is a
#    decision someone typed rather than a silent fallback.
python3 scripts/provider.py emit --table leads --records records.json \
    --run <run-id> --root .
#   parallax propose --kind business-data --table leads#1:company:string:observed,fit:number:simulated

The row count is counted, never declared. The origins survive into the proposal a human accepts, which is what makes this handoff type-preserving rather than lossy.

Where the guarantee ends, precisely

This is worth stating exactly, because the loose version of it is false.

What is enforced: this provider will not emit observed for a field whose artifact it cannot open and re-hash. That is checked, in both the library and the CLI, and it is what R1 and R2 buy.

What is not, and cannot be: Parallax's runtime cannot verify anything. It has no access to your run directory and may not even be on the same machine — a ColumnSpec.origin reaching it is a supplier's assertion, and any caller hand-typing --table leads#40:company:string:observed is making one with nothing behind it. The runtime says so rather than hiding it: the proposal reads "supplier reports its values observed", not "observed".

So the chain is: this provider verifies, then asserts; the runtime records who asserted; the human accept gate is where an assertion nobody can check gets weighed. Claiming the runtime enforces it would be the same overclaim this whole layer exists to refuse.

The one rule you cannot work around

A field is observed only if you hold the artifact it was read from and can produce it. Everything else — concluded, matched, guessed, averaged — is simulated, and must say what it was inferred from.

A field with neither is refused (UNCLASSIFIED_FIELD). Not defaulted to simulated: that reads as caution and is a fabrication, because it asserts you know the value was produced when you know nothing about it. And it is unrecoverable — Parallax types values at birth and has no operator that adds provenance afterwards, so a field that gets past this point untagged has thrown the distinction away permanently.

Contamination flows one way. A column with nine cited values and one guess is a simulated column. Reporting it as observed because most of it was read is the overclaim the type exists to prevent, and it is the version a dashboard prefers.

Seven rules, and where they came from

Each was derived from a specific observed failure in a prospecting service, not from taste. references/rules.md carries the full statement of each.

R5 and R6 are answered by shape rather than by code here, and that is stated rather than hidden. They exist because that thing was a long-running remote service. This is a script you run inside your own turn: there is no endpoint to authenticate and nothing that keeps running after the turn ends. cancel is implemented anyway, because a run's directory outlives the turn. Implementing an API-key check on a local function to tick R6 would be theatre.

Reading a refusal

Every failure is a typed value, exit code 2, {code, reason, detail?} on stderr — the same shape Parallax uses, so one branch handles both.

Tests

cd skills/simulation/data-provider
PYTHONDONTWRITEBYTECODE=1 python3 -m pytest tests/ -q     # 60 tests

PYTHONDONTWRITEBYTECODE because a same-size edit inside one second reuses stale bytecode, which reports a mutant as survived without ever running it.