T2K Integration tutorial

Runnable tutorial · T2K Core 0.4.4

Build one view without pretending every source agrees.

Three synthetic public-benefit agencies describe the same person through different schemas. Use the real T2K Core runtime to map each immutable envelope, preserve its evidence, propose a canonical view, route an ambiguous entity link, evaluate purpose-limited access, and leave judgment with a human.

Run locally Open read-only demo Inspect the source
synthetic data three source systems real core APIs human-owned review

01 / Run the evidence

Start from the versioned release.

Node.js 20.10 or newer is required. The tag, package versions, and commands are pinned so the tutorial remains reproducible.

terminal60-second local foundation
npx create-t2k@0.4.4 my-integration-hub
cd my-integration-hub
npm start
resultinspectable local decision loop
terminalfull integration-hub reviewer app
git clone --branch core-v0.4.4 --depth 1 \
  https://github.com/sigaihealth/t2k-core.git
cd t2k-core
npm ci
npm run build --workspace @t2kai/core
npm start --prefix examples/integration-hub-demo
openhttp://127.0.0.1:4173

Use it like a reviewer

  1. Open each agency and compare its raw fields.
  2. Expand a mapping receipt and trace a value to its source.
  3. Inspect the unresolved name and preserved addresses.
  4. Compare the ambiguous entity candidates.
  5. Contrast the explicit allow with the default deny.
  6. Record a human disposition and inspect the audit item.

Refresh deliberately: the review log is session memory, while the proposal is rebuilt from source evidence.

The 60-second scaffold proves the local decision contract and does not pretend to include agency adapters. Use the full reviewer app for source mapping, reconciliation, entity resolution, policy receipts, and the human disposition flow.

Focused verification npm test --prefix examples/integration-hub-demo
Packaged-consumer smoke npm run smoke --prefix examples/integration-hub-demo

Validate adapters against the downloadable ontology schema. Its governed field mappings, identity keys, drift and late-arrival policies, replay contract, and human checkpoint match the released Core 0.4.4 integration contract.

02 / Architecture

Treat the ontology as a maintenance layer.

The hub is not one monolithic replacement system. Each agency can change at its own pace because mappings, authority, policy, and review remain explicit versioned boundaries.

Mapping

Receipts, not hidden transforms

Every mapped record retains source identity, observation time, mapping hash, payload hash, and field-level provenance.

Reconciliation

Conflict stays visible

Authority can propose a value, but unresolved evidence and preserve-all fields remain inspectable instead of becoming an accidental overwrite.

Entity resolution

Ambiguity routes to review

Equal candidates produce a deterministic, reversible proposal. The demo never silently links or merges an entity.

Purpose access

Unlisted use fails closed

An assigned case coordinator can receive an explicit allow receipt. An undeclared model-training purpose receives default deny.

03 / Human + AI

Complement judgment without impersonating it.

The demo makes the boundary visible: AI assistance can prepare the evidence, while a human owns the disposition. Neither action activates production data.

AI assistance may Human or trusted service must
Summarize conflictsAuthenticate the reviewer
Trace candidates to receiptsAccept, reject, or revise
Score reversible candidatesApprove a link or merge
Explain access receiptsEnforce access in the owning IAM system
Prepare a review packetActivate an accepted canonical revision

The browser's human attestation demonstrates a workflow boundary, not identity proofing. A production service still needs independent authentication, authorization, durable audit, and separation of duties.

04 / Production boundary

Know exactly what this demo does not do.

A useful tutorial should expose its limits. These are deliberate seams for an application to implement, not features hidden behind an environment variable.

Session demo

In-memory review log

The UI records a disposition only for this server process. It does not authenticate a person, mutate source evidence, or activate canonical truth.

refresh-safe proposal · ephemeral log
Durable lifecycle

Postgres is application code

Use PostgresReferenceLifecycle from a trusted service for durable decision episodes, receipts, observations, review, promotion, and rollback.

@t2kai/core/postgres
Agent interface

Integration tools stay read-only

The MCP package keeps mapping, reconciliation, entity-resolution, and access-policy tools read-only. Local lifecycle mutations are a separate explicit opt-in and remain bound to a configured agent identity.

@t2kai/mcp@0.3.1

Continue building

Replace one synthetic adapter at a time.

  1. Copy a source fixture to a new immutable envelope.
  2. Give it a new source record key, locator, event time, and payload record ID.
  3. Version the mapping and ontology when semantics change.
  4. Version authority and access policy when decision rules change.
  5. Keep proposal, review, activation, and downstream execution separate.

Release 0.4.4

Inspect the proposal before trusting the integration.

Run the app, read the receipts, and change one versioned boundary at a time.

Open the tagged demo Developer overview