← All guides

Building a POC vertical — from your claims to a deployed adjudicator

What an engineering team needs to take one domain of their own from source documents to a container that answers claims deterministically, with a signed record of every answer, and to know before they start which outcomes the platform can and cannot deliver. This is the guide to read once end to end; the API walkthrough has every call, authoring a domain has every contract, and evidence packages and policy has the formats behind the last two steps.

What you are building

A domain adjudicator: a frozen container that takes a claim in plain language and returns a verdict — VERIFIED, CONTESTED, UNCERTAIN or HALLUCINATED — with the evidence it relied on: the entity pair the verdict is about, its grounding strength, contradictions crossed, and a demotion_reason when a verdict was lowered. On top of the verdict, your policy turns it into a disposition — ALLOW, REVIEW or DENY — by rules you wrote and can read. Every answer comes with a signed evidence package naming exactly what produced it. The same claim against the same frozen domain returns the same verdict, the same disposition, every time.

It is not a language model, a search index, or a rules engine. It constrains claims against a body of evidence you supply. Treat VERIFIED as "consistent with the corpus, on an asserted pair", never as "true".

Roles, organizations, and what stays with us

Your accounts live in your organization. You see your organization's domains, packages, deployments and evidence and nothing else; another tenant's ids answer 404. Engines and foundational KBs are platform-level and shared. An engine and an approved foundational KB are installed before you arrive, so you begin at the domain step.

Step 0 — write the claims first

Before any corpus work, write the claims your vertical must answer, with the verdict each one should get and the disposition your business needs. Ten to twenty is enough for a POC. Include:

• claims the evidence supports (expect VERIFIED → ALLOW)
• their exact negations (expect CONTESTED → DENY)
• claims about pairs the evidence never mentions (expect UNCERTAIN → REVIEW)
• at least one closed-world case — a list that is exhaustive in reality but is not a denial in prose (expect UNCERTAIN from the engine and, once you write the rule in step 6, DENY from the policy)
• claims about entities the corpus does not name at all (expect HALLUCINATED → DENY)

This list is your acceptance test. Every later step is judged against it, and it is what an engine example check will run for your domain when we bundle it.

Step 1 — the corpus

Upload .md, .txt, .html, .pdf, .docx or .csv. Anything that is not markdown is converted to markdown at upload; the original is kept beside it and the record says which converter ran. Conversion preserves what is there — headings, paragraphs, lists, tables — and adds nothing. A scanned PDF has no text layer and is refused.

The extractor forms a belief about two entities only when the vocabulary already links them (step 2) and the two mentions fall within its window. On engine v0.65.0 that window is 25 entity mentions in document order, not a sentence: two entities in adjacent sentences are paired, and the relation they are given is the verb found near them. A run of short list-style sentences ("The gold policy covers fire. The gold policy covers flood.") can therefore produce beliefs the corpus never stated, such as fire covers flood, and those verify. Write for that, whatever the file type:

• One fact per sentence, entity named in every sentence. "Atlas settles the EUR currency." — not a matrix sentence listing four acquirers, and not a table row. A converted table stays a table; it is legible to a reviewer and invisible to the extractor. Add the plain-fact sentences.
• Keep unrelated facts apart. Because pairing spans sentences, separate facts about different pairs with prose or paragraph breaks rather than stacking them in a list, and check the belief store (step 4) for beliefs between entities you never related. Any you find are extraction artefacts and will verify unless you rewrite the passage.
• Exclusion words are not denials to the extractor. "excludes", "only", "except" carry no negation; a pair's polarity is decided by whether every sentence mentioning it is negated, so one "excludes flood" sentence cancels an explicit "does not cover flood". State denials with "not" and do not mix them with exclusion phrasing about the same pair; where you need a closed-world rule, put it in the policy (step 6).
• The names claims will use. If claims say Atlas and the corpus says Atlas EU, declare an alias (step 2); nothing guesses.
• Repeat stable predicates. settles used consistently teaches one relation; four synonyms teach four weak ones.
• State denials plainly where the corpus actually denies something. A denial lands only where the two concepts co-occur.
• Explain why a rule exists. Prose gives the extractor the co-occurrence it needs; bare bullets do not.

Keep the long-form prose too; the plain-fact sentences are the part the adjudicator grounds on, the prose is what makes the domain legible to a reviewer.

Step 2 — the vocabulary

The vocabulary decides which words are concepts and which pairs may ever be asserted. Read authoring a domain § Assert the pairs your claims are about before writing it. In short:

• a band per concept type (acquirers, schemes, …) with its anchor first;
• a band per named entity your claims are about, anchored on that entity, listing exactly what the corpus supports about it — and nothing more, because a band is a declaration of which pairs may be asserted;
• anchor_chain() linking the type bands into one connected region;
• ALIASES for every long form the corpus uses;
• literals only: the module is parsed as data and never executed.

Save it with PUT /tuning-runs/{id}/vocab-draft (in the builder: Author manually opens the editor with a starter template, Import draft takes your .py file); the response carries the validator's verdict on the contract. Fix errors there, not hours later in a build. No external model is involved unless you choose Generate; if generation is not configured on your platform, Step 1 says so and the two authoring routes are what you use.

Step 3 — the curriculum

A DAG of lessons. Each lesson teaches propositions (short subject-verb-object sentences over grounded tokens) and is assessed on (a, b) pairs the engine must connect unaided. Order lessons bottom-up: parts and names first, relations after. Put the named-entity facts in their own lesson (the example's PR.5) so their assessments show you directly whether those pairs took hold.

A failed lesson stalls its dependents. That is the intended behaviour: it names the gap. Fix the corpus or vocabulary the gap points at, not the assessment. As with the vocabulary: Author manually or Import curriculum (.json) in Step 2, then edit in Step 3; generation is optional.

Step 4 — run it, and read it before you test it

1. Approve the vocabulary, build the domain KB, approve the curriculum, run school. Read school_summary: every lesson should be mastered; an unmastered lesson lists its unreachable assessments.
2. Accept the school result and train. Training ingests the corpus onto the schooled brain and reports entities, edges, relations and beliefs.
3. Check the belief store before you send a single claim: GET /domains/{id}/kg/beliefs?query=<entity>. Every pair your claims need must appear as a three-word proposition (atlas settles eur). If a pair is missing, no claim about it can verify; go back to steps 1–2.
4. Now run your step-0 claims as a batch test with expectations: in the "Domain testing" dialog write one claim per line as claim | EXPECTED_VERDICT | EXPECTED_DISPOSITION (over the API: expectations on POST /domains/{id}/adjudication-runs). The result reports expected versus actual per claim and whether the whole list matched, so the acceptance test is run by the platform, not by eye. Read the fields, not just the label:

Iterate until your list is green. Test runs write "Verifier claim" entries into the working belief store; they never count as asserted pairs, and the frozen package is built from the trained checkpoint. Every test run is recorded as a signed evidence package (step 7); download it from the result modal if you want to keep the run.

Step 5 — freeze and deploy

POST /tuning-runs/{id}/freeze-domain produces an immutable, portable package (grounded KB, trained checkpoint, an earl-verify binary for the container platform, a small FastAPI server, your policy and its evaluator, an identity record, Dockerfile, Compose file, curl examples, manifest) with a codename, a hash, and a substrate identity: one sha256 naming exactly what the package runs — the engine binary, the KB, the checkpoint, the policy. It is on the package, on every deployment built from it, in the container's GET /identity and every reply, and in every evidence package. "What you deployed is what you tested" is a string comparison, not a belief.

POST /deployments builds and starts it under Compose on the platform host; poll until running. Then call it — through the platform, under your normal bearer token (the "Test a claim through the platform" card on the deployment page does exactly this):

POST /api/deployments/{id}/verify      {"candidate_text": "Atlas settles eur currency"}
GET  /api/deployments/{id}/health

The platform forwards the request to the container and returns the container's own reply unchanged under result — a pass-through, not a re-adjudication — together with a signed evidence package for the exchange. A non-running deployment returns 409; a container that does not answer returns 502, never a fabricated verdict. If the container's stated identity differs from the platform's record, substrate_identity_mismatch is true and the reply says so.

Inside the platform host the container also answers directly on its runtime port (curl-examples/ in the package), and the frozen archive is downloadable and runs anywhere Docker runs, with no platform present — which is how a vertical leaves the POC. Standalone, it answers with its identity but does not sign; signing is the platform's.

Step 6 — the policy: exhaustiveness beside the adjudicator, not inside it

The adjudicator will not invent a denial from a closed-world list, and on current engines it will not verify a pair the corpus never asserts either. So a claim like "Northstar supports the amex scheme", against a corpus that says Northstar takes Visa and Mastercard only, comes back UNCERTAIN with relation_unasserted — honest, and not a denial.

If your vertical must say no to that, write it as a rule in the domain's policy (PUT /domains/{id}/policy, or the "Post-verdict policy" card):

{"format": "earl-domain-policy/1", "name": "payments v1",
 "rules": [
   {"id": "northstar-schemes", "type": "closed_world", "entity": "northstar",
    "permitted": ["visa", "mastercard"], "action": "deny",
    "reason": "Northstar supports Visa and Mastercard only"},
   {"id": "asserted-pair", "type": "require_asserted_pair", "action": "review"},
   {"id": "clean", "type": "max_contradictions", "max": 0, "action": "deny"}]}

The policy is deterministic, versioned, and small enough to read in one sitting. Rules only ever raise a disposition (ALLOW → REVIEW → DENY), so no rule can make a contested claim pass. It runs after the verdict on the working checkpoint during your tests and inside the container for a frozen package — the very same evaluator file — so what you tested is what deploys. The full rule set is in evidence packages and policy § 3.

Step 7 — keep the evidence

Every adjudication, in testing or through a deployment, yields an Ed25519-signed evidence package: the full result with every claim field, bound to the substrate identity, the engine, the KB and checkpoint fingerprints, the policy hash and the claims asked. List them per domain or deployment, fetch any by id, and verify one offline with nothing but the file and the platform's public-key fingerprint:

python verify_evidence_package.py evidence-<id>.json --pin-key <key_id>

Get the script at GET /api/evidence/verifier and the fingerprint at GET /api/evidence/public-key, once, and keep the fingerprint with your trust anchors: --pin-key is the check that proves a package came from this platform and not merely from a consistent signer. Exit status 0 means every check passed. What each check proves is in evidence packages and policy § 2.1.

Replay any package (the "Replay and compare" button, or POST /api/evidence-packages/{id}/replay) to re-adjudicate its claims on the same source and get a signed comparison: identical, or a named list of what changed. Together, a package's fingerprints, its verdict evidence with expected-versus-actual, and its replay comparison are the export an evaluator asked for.

Known defect in engine v0.65.0 — read before relying on a VERIFIED

A diagnostic audit on 2026-09-22 (Jou Labs, on the pinned evaluation build) found that engine v0.65.0 produces false VERIFIED verdicts from correct source text. The mechanism is in evidence construction, not in your authoring: the extractor pairs entities that co-occur within a window of mentions rather than within a stated relationship, so adjacent sentences, coordinated lists ("fire, theft and storm") and table rows generate beliefs the corpus never asserted, and those beliefs verify. Separately, the pair-assertion check does not test the direction of a relation, so a reversed claim ("Fire covers the basic policy") verifies. On the audit corpus 11 of 31 evaluated claims were false VERIFIED.

What this means for your evaluation:

• Treat a VERIFIED on this build as "an asserted pair with an affirmative belief in the store", not as reliable semantic verification of the stated relationship. Read endpoints, endpoints_asserted and the belief store behind a verdict before acting on it, and run your acceptance list with expected outcomes so mismatches are counted rather than noticed.
• CONTESTED and UNCERTAIN verdicts were not found to be affected in the audit; the defect produces false positives, not false negatives.
• This build is preserved unchanged (tag ey-eval-2026-09-22) so that findings against it stay reproducible. A repaired engine will be a new release, gated by the compatibility check, and announced; the first candidate repair (sentence-scoped pairing) did not meet its acceptance and is not released. The remediation record is maintained by Jou Labs.

What is available today, demonstrated separately, and planned

Stated so you can plan around it rather than discover it. This guide describes the evaluation build you are using (platform commit d570fab, tag ey-eval-2026-09-22, engine v0.65.0); that build is pinned and will not change under you.

Available today, on this platform, self-serve

• Document claim adjudicators: corpus (markdown, text, HTML, PDF, Word, CSV), vocabulary and curriculum (authored or imported), school, train, batch tests with expected outcomes, policy, freeze, deploy, and calls through the platform.
• Signed evidence packages for every adjudication, with substrate identity, offline verification and replay.
• Organizations and roles; new domains are created on the current engine release automatically.

Demonstrated separately, available for integration through Jou Labs

• Action authorization against a sealed rule contract, with a hash-chained ledger, signed evidence and replay: the containment runtime behind the evaluation console at /eval/. It is not yet something an organization authors and deploys itself on this platform.

Planned, not yet built

• A capability-oriented developer API and SDK so an application can call evidence evaluation, authority checks, recording, verification and replay individually from its own code, and compose them into one signed workflow record with human approvals. Document adjudicators and authorization gateways become templates on that foundation. This is chartered as a draft and not yet scheduled.
• Per-deployment public routes with their own API keys; a platform-side exhaustiveness layer beyond the five policy rule types; model-assisted drafting on this host.

Limits that will not change with any of the above

• The adjudicator does not generate text, summarise, retrieve passages, answer open questions, chain reasoning steps, do arithmetic or date logic, or reconcile facts across documents. Those belong in your application.
• A verified evidence package proves integrity, attribution and reproducibility of the recorded computation. It does not prove the evidence was true.
• Engine behaviour is versioned. A domain is bound to the engine it was created on; a newer engine must pass the compatibility gate first.

POC readiness checklist

• [ ] Step-0 claim list written, with expected verdicts and dispositions, including negations, an unmentioned pair, a closed-world case and a hallucination
• [ ] Corpus: one fact per sentence for every claimed pair; aliases declared
• [ ] Vocabulary: a band per named entity, listing only what the corpus supports
• [ ] School: every lesson mastered
• [ ] Belief store shows every needed pair as a three-word proposition
• [ ] Every step-0 claim returns its expected verdict on the asserted pair
• [ ] Policy written; every closed-world case returns its expected disposition with a rule and reason a reviewer can read
• [ ] Frozen package built; deployment running; a claim answered through the platform with substrate_identity_mismatch: false
• [ ] The step-0 list run as a batch test with expectations: all_matched: true
• [ ] One evidence package verified offline with --pin-key, exit 0, and replayed with identical: true
• [ ] Verdict fields (endpoints_asserted, demotion_reason) and the policy reviewed by someone who did not write the corpus

Determinism and data handling

• Identical claims return identical verdicts, dispositions and prompt hashes across calls and across restarts of the same frozen package; the substrate identity says when two deployments are the same package.
• Nothing you upload leaves the platform. The only calls to an external model are generate-vocab and generate-lessons, and both are optional: author the drafts yourself and no external model is in the path at all.
• A frozen package records the engine release and commit, the binary's hash, the KB fingerprint, every checkpoint file's hash and the policy hash in its manifest, and the substrate identity over all of them, so what you deployed is what you tested.
• Evidence packages are signed with a key that never leaves the platform; the public key and its fingerprint are published for you to pin.