NextGraph Link Language for AD4M

Decentralized link language using NextGraph as the storage and sync backend. Built with the modern ALDK (AD4M Language Development Kit) pattern.

Architecture

┌──────────────────────────────┐
│  AD4M Executor (Deno)        │
│  ┌────────────────────────┐  │
│  │ NextGraph Link Language │  │
│  │ (ALDK — this repo)     │  │
│  └──────────┬─────────────┘  │
│             │ httpFetch       │
└─────────────┼────────────────┘
              │ HTTP
┌─────────────▼────────────────┐
│  NextGraph Gateway (Node.js) │
│  ┌────────────────────────┐  │
│  │ @ng-org/nextgraph WASM │  │
│  │ ├── Wallet management  │  │
│  │ ├── SPARQL engine      │  │
│  │ └── CRDT sync          │  │
│  └────────────────────────┘  │
└──────────────────────────────┘

The language runs inside the AD4M executor's Deno sandbox and communicates with a sidecar gateway (Node.js process) via HTTP. The gateway wraps the NextGraph WASM SDK, handling wallet management, SPARQL operations, and CRDT-based synchronization.

This follows the same pattern as the Hypercore link language.

Key Features

• Local-first CRDT: Data is stored in NextGraph's encrypted wallet with CRDT-based conflict resolution
• P2P sync: Automatic peer-to-peer synchronization via NextGraph brokers
• RDF triples: Links stored as SPARQL triples with full metadata (author, timestamp, proof)
• Sovereign identity: NextGraph wallet-based identity (Ed25519)
• Encrypted at rest: All data encrypted in the NextGraph wallet
• Offline capable: Local reads and writes work without connectivity

Quick Start

1. Start the Gateway

cd gateway/
npm install
PORT=7779 STORAGE_PATH=./data tsx index.ts

2. Build the Language

npm install
deno run --allow-all esbuild.ts

3. Publish to AD4M

Use ad4m-cli to publish build/bundle.js with the template parameters:

• NEXTGRAPH_GATEWAY_URL — URL of the sidecar gateway (e.g. http://localhost:7779)
• NEXTGRAPH_REPO_ID — NextGraph repo/store ID for this neighbourhood
• NEIGHBOURHOOD_META — AD4M neighbourhood metadata

Template Variables

Variable	Description	Example
NEXTGRAPH_GATEWAY_URL	URL of the NextGraph sidecar gateway	http://localhost:7779
NEXTGRAPH_REPO_ID	NextGraph repo ID for this neighbourhood	did:ng:repo:abc123
NEIGHBOURHOOD_META	AD4M neighbourhood metadata	My Neighbourhood

Capabilities

Capability	Status	Notes
perspective-commit	✅	Store locally + push to gateway as SPARQL triples
perspective-sync	✅	Poll gateway for changes, apply diff
perspective-query	✅	Local indexed store (by source, target, predicate)
peers	✅	Basic peer tracking
telepresence	❌	No ephemeral messaging API in NextGraph yet
interactions	❌	Not applicable for link languages

Development

Run Tests

npm test
# or
node --experimental-vm-modules --import tsx --test tests/*.test.ts

Build

npm run build
# or
deno run --allow-all esbuild.ts

Project Structure

nextgraph-link-language/
├── index.ts              # defineLanguage() entry point
├── esbuild.ts            # Deno esbuild bundler
├── package.json
├── tsconfig.json
├── src/
│   ├── types.ts          # Shared AD4M types
│   ├── store.ts          # Local link store with indexes
│   ├── transport.ts      # Transport interface
│   ├── transport-deno.ts # Deno transport (wraps httpFetch)
│   ├── storage-interface.ts # Storage adapter interface
│   ├── storage-deno.ts   # Deno storage adapter
│   ├── nextgraph-api.ts  # Pure HTTP client for gateway
│   ├── sync.ts           # Sync logic (poll + diff)
│   └── translate.ts      # LinkExpression ↔ NextGraph triple translation
├── tests/
│   ├── store.test.ts     # Local store tests
│   ├── translate.test.ts # Translation tests
│   └── sync.test.ts      # Sync tests with mock transport
└── gateway/
    ├── index.ts          # NextGraph sidecar gateway (Express + WASM)
    ├── package.json
    └── README.md

How Data Flows

Commit (local → remote)

1. commit(diff) called by AD4M executor
2. Links stored in local KV store (indexed by source/target/predicate)
3. Links translated to NextGraph triples (linkToTriple)
4. Triples sent to gateway via POST /triples
5. Gateway executes SPARQL INSERT on NextGraph repo
6. NextGraph CRDT propagates to peers via broker

Sync (remote → local)

1. sync() called periodically by AD4M executor
2. Gateway polled via GET /sync?since=<revision> for incremental changes
3. Falls back to GET /triples full fetch if incremental fails
4. New triples translated to LinkExpressions (tripleToLink)
5. Diff computed and applied to local store
6. emitPerspectiveDiff() notifies local subscribers

License

MIT