Skip to content

About

Partial reference resolver for 4D-ID 2.4: caller-grounded records, aliases, registrations, lifecycle, and bounded reconciliation.

Topics

Resources

Code of conduct

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

4D-ID Reference Resolver

The reference implementation of the 4D-ID specification: a resolver you can run in an afternoon.

test License: Apache-2.0

⚙️ 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.

Install and run

npm install
npm start            # resolver on http://localhost:4141, seeded with a sample facility

Or with Docker:

docker compose up -d --build

The 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).

The four-call quickstart

# 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.

Reconciliation: two systems, one thing

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.

Configuration

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

Test

npm test    # schema validation + resolver smoke + HTTP end-to-end + conformance + reconciliation

The 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.

What it implements

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.

License

Apache-2.0. See LICENSE. Built against the 4D-ID 2.4 working draft offered for community review.

About

Partial reference resolver for 4D-ID 2.4: caller-grounded records, aliases, registrations, lifecycle, and bounded reconciliation.

Topics

Resources

Code of conduct

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages