The reference implementation of the 4D-ID specification: a resolver you can run in an afternoon.
⚙️ Runtime: Node 22, ES modules. No native build required by default.
🗄️ Storage: pure-JS in-memory (default) or SQLite (STORE=sqlite).
🌐 Bindings: REST today (matches openapi/openapi.yaml); MCP to follow.
4D-ID begins after grounding: this resolver does not perceive, localize, register, or render the world. It stores and resolves caller-supplied identities, grounding, state, registrations, and evidence. It is a reference, not a production service: single process, single store, no authentication. Authority strings are attribution only; deployment policy must authenticate and authorize operations.
This resolver exists to prove the spec is buildable, to provide a reference target for the current conformance checks, and to give you something to run behind the four-call quickstart. The production shape (PostGIS, stateless behind the Part 4 architecture) is a separate build.
npm install
npm start # resolver on http://localhost:4141, seeded with a sample facilityOr with Docker:
docker compose up -d --buildThe default deploy needs no C++ toolchain: it runs on a pure-JavaScript store. Set STORE=sqlite for persistence (needs build tools for the SQLite binding).
# resolve an external identifier to a 4D-ID
curl "localhost:4141/resolve?registry=asset.register&external_id=TB-WH-01"
# a compact, agent-ready context envelope
curl "localhost:4141/entity/<4did>/context"
# the best representation for a purpose
curl "localhost:4141/entity/<4did>/representations?purpose=agent-context"
# changes since a generation
curl "localhost:4141/watch?cells=<zone>&since=0"resolve is a lookup, not a mint: it finds an identity already present in resolver records. Grounding and external identifier mappings are supplied by the caller or deployment. Exact external identifiers must not be rebound silently; conflicts require review. To create identities, POST /ingest (blocked in read-only deployments), or try the live demos, which create isolated sandbox records client-side.
Two systems can hold different identities for the same subject. This resolver implements bounded cross-system identity reconciliation (Part 4, §15.2): an external matcher proposes a time-limited candidate with evidence; an authority-attributed operation records a decision, and deployment policy, not this unauthenticated API, determines whether that authority is authorized. Candidate evidence never merges by itself. The earlier-genesis identity survives while the other redirects and keeps its derivation.
curl -X POST localhost:4141/reconcile/propose -H 'content-type: application/json' \
-d '{"a":"<4did-a>","b":"<4did-b>","confidence":0.94,"by":"external-matcher:v1","method":"reviewed-crosswalk","evidence":["evidence:tag","evidence:registration"]}'
curl -X POST localhost:4141/reconcile/merge -H 'content-type: application/json' \
-d '{"a":"<4did-a>","b":"<4did-b>","candidate_id":"<candidate-id>","authority":"warehouse-ops:declared"}'
curl "localhost:4141/entity/<4did-a>/merge-history"POST /reconcile/split is the inverse: one identity becomes several, each derived from the original. Try the interactive walkthrough at 4d-id.org/reconcile.html.
| Variable | Default | Meaning |
|---|---|---|
PORT |
4141 |
HTTP listen port |
STORE |
memory |
memory (no persistence, no native build) or sqlite |
DB_PATH |
4did.db |
SQLite file when STORE=sqlite |
SEED |
true |
load the sample facility on start |
npm test # schema validation + resolver smoke + HTTP end-to-end + conformance + reconciliationThe 2.4 manifest defines 112 targets. The data runner implements 15 schema checks; functional work continues across registrations, reconciliation limits, authority policy, propagation, security, and domains. See the conformance manifest.
A partial core, fabric, lifecycle, and scale implementation over the Clause 10 access operations. It supports spatial-form IDs, the 2.4 non-spatial id variant, exact-alias conflict rejection, bounded candidate lists, authority-attributed merge/split decisions, snapshots, list-then-watch, and context envelopes. It does not implement authentication, the full authority model, or full functional conformance.
Apache-2.0. See LICENSE. Built against the 4D-ID 2.4 working draft offered for community review.