@btusbefw/dkg-experiment-ledger 0.1.0

package/DEMO.md

@@ -0,0 +1,11 @@
+# Recorded walkthrough
+
+`demo/walkthrough.cast` is an actual recorded terminal session (asciinema v2), not invented terminal output. `demo/transcript.txt` is its readable transcript. Play the recording with `asciinema play demo/walkthrough.cast`, or upload it using the new dedicated project identity when preparing the public submission.
+
+The walkthrough runs `scripts/demo-session.mjs` against a real DKG 10.0.16 node. It records two measured regression results, detects a repeated record, reads and compares the stored runs, explicitly shares the candidate with Curator authority, and queries its self-attested data from Shared Memory. Two-second pauses make the output easier to read.
+
+The example's deterministic held-out mean squared errors are approximately 0.7939276 (degree one) and 0.00495805 (degree three). These are measurements on the included synthetic example, not a claim of real-world model improvement. The dataset, source, parameters, and record digests are preserved.
+
+The node is isolated with no external peers and a mock chain. The recording proves local API functionality and sealed sharing, not public replication, mainnet publication, or payment. The public hosted demo URL is pending the dedicated account setup.
+
+To reproduce: configure a local registered-agent token and an existing test Project, run `node examples/autoresearch.mjs --offline`, then run `node scripts/demo-session.mjs`. Use a fresh disposable Project if you want the first writes shown as new records rather than idempotent replays. Do not use a production project for this demo: the script deliberately performs SHARE.

package/DESIGN.md

@@ -0,0 +1,57 @@
+# Design brief: reproducible experiment memory
+
+## Problem and target user
+
+An autoresearch loop can lose the reason an experiment was kept or rejected when its session ends. A notebook cell's printed metric alone does not identify the evaluated data, source, settings, or author. DKG Experiment Ledger gives coding/research agents and Jupyter kernels a small explicit record boundary, preserving those relationships in a project-scoped knowledge graph.
+
+This addresses the Round 1 call's named autoresearch and Jupyter/notebook integration targets. The end-to-end example actually trains two regressions, stores their measured held-out results, retrieves them from DKG, and compares compatible metrics. The integration can be used without a hosted LLM, framework plugin, paid model API, or a second persistence service.
+
+## Architecture
+
+```text
+Autoresearch agent / Jupyter kernel
+     | explicit JSON result + source/data fingerprints
+     v
+Validate -> canonical digest -> deterministic Knowledge Asset name
+     | public authenticated HTTP
+     v
+Project / Context Graph -> private Working Memory
+     | read-back and content-digest check
+     +-> scoped SPARQL recall -> compatible-run comparison
+     |
+     +-> explicit Curator-authorized SHARE -> Shared Memory
+                                                    |
+                          official agent PUBLISH conversation
+                                                    v
+                       Verifiable Memory / actual UAL -> oracle
+```
+
+The CLI is the primary agent surface. The Python helper accepts an explicit record from an existing kernel; it does not execute or scrape a notebook. The JavaScript library exposes the same operations. These surfaces all call the public HTTP API; no internal DKG imports, node patches, or direct SPARQL updates are used.
+
+## Data model and trust
+
+Each run is a named Knowledge Asset whose root Entity is a `urn:sha256:` content identifier. Standard PROV predicates associate attribution and observation time; integration predicates expose the experiment, dataset fingerprint, source revision, typed numeric metrics, and a canonical JSON payload. The payload is authoritative for comparisons. Its SHA-256 detects corruption relative to the deterministic name; it does not prove the author's measurements are true or certify unrelated RDF statements.
+
+Private drafts remain self-attested. The experiment and evaluation-data fingerprint must match before comparing runs; metric units and optimization direction must also agree. Parameter/source changes are exposed, and the output expressly avoids statistical/causal claims. Dataset fingerprints should cover evaluation splits and preprocessing. No UAL is synthesized before publication.
+
+## DKG v10 primitives and authority
+
+Projects scope every operation via the exact Context Graph ID. Records use the Knowledge Asset create/write lifecycle, and read-back verifies the actual stored payload. The Curator retains control of SHARE through DKG's authorization path. An explicit exact-project confirmation protects the privacy transition. No public-project fallback, privilege substitution, or `skipSeal` downgrade is implemented.
+
+The registry install kind is `cli`, public interface `http-api`, and memory layers `WM`/`SWM`. The product calls it Shared Memory as in the bounty; the node's API view literal remains `shared-working-memory`. The CLI creates no Context Graphs; the operator selects an existing Project. Test setup creates disposable Context Graphs outside the shipped operational surface.
+
+## Promotion path and oracle readiness
+
+The author or Curator reviews the source hash, evaluation fingerprint, declared artifacts, and reproducibility evidence in Working Memory. Authorized SHARE invokes the node's full sealing path, preserving the Entity, assertion lineage, metrics, and provenance into Shared Memory. When the team decides an experiment warrants permanence, the official DKG agent conversation handles PUBLISH and its fees. The resulting real UAL can be paired with the content digest and source/data hashes in an oracle input.
+
+Sealing is an integrity/authorship step, not independent verification of a metric. Endorsement and consensus verification remain conversational DKG operations, not UI buttons. This integration does not automatically spend TRAC, endorse results, or declare self-attested data consensus-verified.
+
+## Reliability, validation, and limits
+
+Validation is bounded to 128 KiB and rejects non-finite metrics, unsafe field shapes, incompatible comparisons, and credential-bearing URLs. Read-after-write catches storage/format errors. Completed replays are idempotent even where the tested DKG runtime's `alreadyExists` flag misses an agent-specific record. Partial writes require reconciliation of the deterministic name; mutations are never blindly retried.
+
+Tests use DKG 10.0.16, Oxigraph, registered local-agent tokens, and a mock chain. They cover real storage/query/SHARE, not a mocked HTTP service alone. No public-network replication, blockchain settlement, or multi-node confidentiality claim is made. The current command surface is bounded to 100 listed runs (up to 1,000 through the library); pagination, notebook UI, and remote artifact verification are future work.
+
+## Maintenance
+
+The release is dependency-free, with unit tests and an isolated real-node suite that can detect lifecycle changes. The submitting operator must name the dedicated maintainer and accept the required six-month support window. This draft does not invent that identity or attest on their behalf.

package/LAB.md

@@ -0,0 +1,43 @@
+# Isolated DKG validation lab
+
+Tested 2026-09-09 with the published `@origintrail-official/dkg@10.0.16`, reported source commit `ef7e7400ff1571fd31cc0c39110fa335949f444d`, Node.js 25.6.0, macOS arm64. The library requires Node 22+. The node uses Oxigraph plus its own SQLite metadata store.
+
+The test install lives under `/tmp/astra-dkg-lab`, with a separate `DKG_HOME=/tmp/astra-dkg-lab/state`. It does not use an existing node, personal wallet, browser account, npm login, GitHub credential, or mainnet funds. Installation used empty npm user/global configs and a temporary cache. Lifecycle scripts were initially disabled; only the required `better-sqlite3` native dependency was subsequently rebuilt. No DKG source was patched.
+
+The lab config selects the bundled testnet genesis but overrides the chain adapter to `mock:31337`, disables relays (`relay: "none"`), sets an empty bootstrap list, and disables telemetry. The API binds `127.0.0.1:19200`. On macOS the process additionally runs through `sandbox-exec` with non-loopback network traffic denied. This blocks incidental upstream node update checks as well as public peer/RPC traffic. Status reported zero connected peers.
+
+Example config (new disposable directory only):
+
+```json
+{
+  "name": "astra-experiment-lab",
+  "networkConfig": "testnet",
+  "apiPort": 19200,
+  "apiHost": "127.0.0.1",
+  "listenPort": 0,
+  "nodeRole": "edge",
+  "relay": "none",
+  "bootstrapPeers": [],
+  "chain": {"type": "mock", "chainId": "mock:31337"},
+  "store": {"backend": "oxigraph-persistent", "options": {"path": "/tmp/astra-dkg-lab/state/store.nq"}},
+  "autoUpdate": {"enabled": false},
+  "telemetry": {"enabled": false},
+  "contextGraphs": [],
+  "contextGraphSubscriptionRehydrationEnabled": false,
+  "rfc64Catalog": {"enabled": false}
+}
+```
+
+Start the official CLI with `DKG_HOME` set to that directory. Register a **disposable local agent** through `POST /api/agent/register`, store the returned token privately, and use it for tests. Never print the returned private key/token or include the runtime state in a release. The regular node-admin token without a wallet created legacy draft graphs that the version's broad WM query did not discover; the registered-agent path passes.
+
+```sh
+export DKG_URL=http://127.0.0.1:19200
+export DKG_TOKEN_FILE=/tmp/astra-dkg-lab/state/ledger.token
+DKG_TEST_LOCAL=1 npm run test:integration
+```
+
+Both `backend: oxigraph-persistent` and `store.options.path` are essential: `backend: oxigraph` is in-memory and ignores a path option. Restart checks caught that lab misconfiguration; durable checks use the persistent adapter and file path above. The test creates uniquely named disposable Projects. It refuses nodes with a different lab name, a non-loopback URL, or connected peers. Delete only the disposable lab after recording evidence. The tests do not validate public-network gossip, blockchain settlement, an exchange off-ramp, or sponsor payment.
+
+Runtime-specific observations are captured in regression behavior: generated auth.token files include comment lines; query bindings are nested under `result.bindings`; `alreadyExists` can miss custodial records. The integration handles the first two and uses content read-back instead of trusting the third.
+
+Final persistence check passed: the recorded asset and digest were read using the same registered-agent token after stopping and restarting the persistent node. Evidence is retained in the parent execution directory.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DKG Experiment Ledger contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# DKG Experiment Ledger
+
+Record reproducible experiment results in a DKG v10 Project, then retrieve and compare them from an autoresearch agent or Jupyter kernel. The integration uses the node's public HTTP API. It has zero runtime dependencies and never executes the recorded command or reads your notebook history.
+
+## Run locally
+
+Requires Node.js 22+ and a running DKG v10 node (tested on 10.0.16). Use a registered agent's token and an exact Context Graph ID that this agent may access. A bare node-admin identity without an EVM agent wallet has incomplete Working Memory discovery on the tested DKG version; register a local agent instead.
+
+```sh
+export DKG_URL=http://127.0.0.1:9200
+export DKG_TOKEN_FILE=/path/to/your/local-agent.token
+export DKG_CONTEXT_GRAPH=your-exact-project-id
+node examples/autoresearch.mjs --offline
+node bin/cli.mjs validate demo-output/degree-1.json
+node bin/cli.mjs record demo-output/degree-1.json
+node bin/cli.mjs list
+```
+
+The offline demo really fits degree-one and degree-three regressions to deterministic synthetic training data and measures held-out mean squared error. Running without `--offline` writes both results to DKG and compares records retrieved from the node. The generated records contain source and dataset SHA-256 fingerprints; `demo-output/receipt.json` records the verified result. This deliberately small numerical example demonstrates the integration, not a claim about general machine-learning performance.
+
+The release package is `@btusbefw/dkg-experiment-ledger` (publication pending).
+
+After publishing/installing the package, `dkg-experiments` replaces `node bin/cli.mjs`. `DKG_API_URL` and `DKG_AUTH_TOKEN` are accepted aliases for registry-provided configuration. Token files may contain DKG's comment header. No token value is printed. HTTPS remote nodes require explicit `DKG_ALLOW_REMOTE=1`; otherwise only loopback destinations are allowed.
+
+## Record contract
+
+See the generated `demo-output/degree-1.json` for a complete example. Required fields:
+
+- `schemaVersion: 1`, `experiment`, `runId`, `observedAt` (UTC ISO), `author` (your agent identifier).
+- `dataset: {name, fingerprint}`. The SHA-256 fingerprint should identify the effective evaluation data, split, and preprocessing protocol; use the same convention throughout an experiment.
+- `code: {revision}`: a full Git SHA or source SHA-256. Optional `repository` must be a clean HTTPS URL.
+- `parameters`: JSON object. `metrics`: named `{value, unit, direction}` entries; direction is `minimize` or `maximize`.
+- Optional `command` (an argument array, stored only), `notes`, and `artifacts` (name, SHA-256, optional media type and clean HTTPS URI).
+
+Only explicitly supplied data is stored. Do not include secrets or personal data in notes, parameters, commands, or artifacts. URL checks reject query strings and embedded credentials, but are not a general secret detector. Artifact hashes are declared provenance; the integration does not fetch or independently verify external artifacts.
+
+## Recall, compare, and promote
+
+```sh
+dkg-experiments show xrun-<48-hex-name>
+dkg-experiments compare xrun-<baseline> xrun-<candidate>
+dkg-experiments promotion-plan xrun-<candidate>
+dkg-experiments share xrun-<candidate> your-exact-project-id
+dkg-experiments list shared-working-memory
+```
+
+`record` writes private Working Memory. Names derive from the canonical record digest, and repeating a completed record is detected through read-back before mutation. A partial/ambiguous write never causes a random replacement asset or a blind write retry; an existing lifecycle without readable payload fails with a recovery message.
+
+Comparisons require the same experiment and dataset fingerprint, and matching metric units/directions. They expose parameter changes and source revisions, refuse incompatible metrics, and avoid dividing by zero. Differences are observations, not causal effects or statistical significance. `list` returns at most 100 records by default (library callers can request up to 1,000); it is not a full unlimited history export.
+
+`share` requires the exact Project ID again, calls the canonical Curator-authorized SHARE route, and lets DKG seal the asset. It never bypasses denial or retries with `skipSeal`. Shared Memory remains self-attested. On-chain PUBLISH is deliberately left to the official DKG agent conversation and the operator's fee authorization. Keep the actual returned UAL for oracle citations; a content hash or a Working Memory name is not a UAL. Shared records are retrieved through `list shared-working-memory`; `show` and `compare` currently read Working Memory.
+
+## Notebook integration
+
+Import `record_experiment` from `examples/notebook.py` into a Jupyter kernel or ordinary Python program:
+
+```python
+receipt = record_experiment(my_explicit_record,
+    cli=["node", "/absolute/path/to/bin/cli.mjs"])
+print(receipt["name"], receipt["digest"])
+```
+
+The bridge forwards only DKG configuration and minimal runtime variables. It uses a private temporary JSON file and a shell-free subprocess call. It does not discover credentials or inspect user accounts.
+
+## Validation
+
+```sh
+npm test
+# Only against the isolated lab node described in LAB.md:
+DKG_TEST_LOCAL=1 npm run test:integration
+```
+
+The real-node suite proves round-trip storage, duplicate detection, project isolation, bad-token denial, comparison, and authorized sealed sharing. `LAB.md` describes the test node and its limitations. See `DESIGN.md`, `SECURITY.md`, and `DEMO.md` for the bounty review materials.
+
+Maintainer identity, publication provenance, and the six-month maintenance commitment must be completed by the submitting operator before registry submission.

package/SECURITY.md

@@ -0,0 +1,20 @@
+# Security and data handling
+
+- Default egress: only the configured loopback DKG node. No telemetry, analytics, wallet calls, model API calls, or third-party artifact downloads.
+- Optional remote mode: `DKG_ALLOW_REMOTE=1` permits an explicitly configured HTTPS DKG host. That host receives the supplied records and token. Declare the actual host if distributing a preconfigured remote deployment. HTTP redirects are rejected to prevent credential forwarding.
+- Credentials: one caller-supplied local DKG token (file or environment); registry aliases are supported. No discovery of GitHub, Google, npm, browser, wallet, or personal-account credentials. The token is never included in record payloads or errors generated from server response bodies.
+- Write authority: `POST /api/knowledge-assets`, `POST /api/knowledge-assets/{name}/wm/write`, and explicit `POST /api/knowledge-assets/{name}/swm/share`. SHARE is a Curator-authority operation and requires exact Context Graph confirmation. DKG remains the authorization boundary.
+- Read-only POST: `POST /api/query`, always scoped to the selected Context Graph and memory view. No direct SPARQL updates.
+- No PUBLISH, endorsement, voting, token approval, staking, payment, or wallet-signing code is present.
+- No install scripts, dynamic code loading, shell evaluation, or remote-code execution. Recorded commands are data. The Python helper uses a fixed argument array and a private temporary file.
+- Records may contain sensitive information supplied by the caller. This is not a DLP/secret-scanning product. Read the record before sharing it; artifact URLs reject embedded credentials and query strings but free-text fields cannot be certified secret-free.
+- Digest verification covers the canonical record payload and its root Entity/name. It is not a proof of experimental truth, external artifact availability, or integrity of all RDF statements a separate actor might add.
+- A caller's deliberate `DKG_AGENT_ADDRESS` override must refer to an identity they are authorized to read. DKG enforces access; the integration does not bypass a denial.
+
+## Recovery
+
+On network timeout, inspect the same deterministic Knowledge Asset name. Repeating `record` reads a completed matching payload before mutation. If a lifecycle exists but its Working Memory payload is absent or incomplete, the operation fails; inspect the node's lifecycle and repair deliberately. Do not delete a shared/published asset just to retry.
+
+## Test boundary
+
+The isolated lab has no external peers, uses a mock chain, and runs under an OS profile that blocks non-loopback traffic. The integration itself uses public HTTP only; the lab uses the official published node with no source patches. Keys/tokens generated by the disposable node are not release artifacts.

package/bin/cli.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import {readFile} from 'node:fs/promises';
+import {ExperimentLedger,encodeRecord,compareRecords} from '../src/ledger.mjs';
+import {loadToken} from '../src/token.mjs';
+
+const usage=`dkg-experiments <command> [arguments]
+  validate <record.json>         Validate and show the deterministic KA name; no network
+  record <record.json>           Write to the configured project's private Working Memory
+  show <KA-name>                 Read and verify a record
+  list [working-memory|shared-working-memory]   Retrieve up to 100 project records
+  compare <baseline-KA> <candidate-KA>          Compare compatible runs in Working Memory
+  share <KA-name> <exact-CG-ID>   Explicit Curator-authorized sharing, sealed by DKG
+  promotion-plan <KA-name>       Describe the promotion path; never publishes
+Environment: DKG_URL, DKG_TOKEN or DKG_TOKEN_FILE, DKG_CONTEXT_GRAPH,
+             optional DKG_AGENT_ADDRESS and DKG_ALLOW_REMOTE=1 (HTTPS only).
+No command creates a project, executes a notebook, or publishes on-chain.`;
+try {
+  const [command,...args]=process.argv.slice(2);
+  const counts={validate:1,record:1,show:1,list:0,compare:2,share:2,'promotion-plan':1};
+  if(!command||command==='--help'){console.log(usage);process.exit(0);}
+  if(!(command in counts)||args.length<counts[command]||args.length>(command==='list'?1:counts[command])) throw new Error(usage);
+  let result;
+  if(command==='validate') {const e=encodeRecord(JSON.parse(await readFile(args[0],'utf8')));result={valid:true,name:e.name,digest:e.digest,quadCount:e.quads.length};}
+  else {
+    const token=await loadToken();
+    const ledger=new ExperimentLedger({baseUrl:process.env.DKG_URL??process.env.DKG_API_URL,token,contextGraphId:process.env.DKG_CONTEXT_GRAPH,agentAddress:process.env.DKG_AGENT_ADDRESS,allowRemote:process.env.DKG_ALLOW_REMOTE==='1'});
+    if(command==='record')result=await ledger.record(JSON.parse(await readFile(args[0],'utf8')));
+    if(command==='show')result=await ledger.get(args[0]);
+    if(command==='list')result=await ledger.list({view:args[0]});
+    if(command==='compare')result=compareRecords((await ledger.get(args[0])).record,(await ledger.get(args[1])).record);
+    if(command==='share')result=await ledger.share(args[0],{confirmContextGraphId:args[1]});
+    if(command==='promotion-plan')result=ledger.promotionPlan(args[0]);
+  }
+  console.log(JSON.stringify(result,null,2));
+} catch(error){console.error(error.message);process.exitCode=1;}

package/demo/transcript.txt

@@ -0,0 +1,77 @@
+DKG EXPERIMENT LEDGER | live local API walkthrough
+{
+  "nodeVersion": "10.0.16",
+  "project": "astra-recorded-demo-final",
+  "connectedPeers": 0,
+  "chain": "Isolated lab mock chain; no public publication"
+}
+
+1. Record two measured regression runs in private Working Memory
+{
+  "run": "degree-1",
+  "knowledgeAsset": "xrun-cfd92f38836000da91c750b60b21b2d6d719976279beaae0",
+  "mse": 0.7939276145811444,
+  "layer": "working-memory",
+  "duplicate": false
+}
+{
+  "run": "degree-3",
+  "knowledgeAsset": "xrun-a723e3ccfa7adf9a2efd0d519f8c5f399e06d80b7abad449",
+  "mse": 0.004958052031565096,
+  "layer": "working-memory",
+  "duplicate": false
+}
+
+2. Replay the identical record: same asset, no second payload
+{
+  "duplicate": true,
+  "sameName": true
+}
+
+3. Retrieve the stored runs from DKG and compare compatible metrics
+{
+  "baseline": "degree-1",
+  "candidate": "degree-3",
+  "metrics": [
+    {
+      "name": "mse",
+      "unit": "squared-error",
+      "direction": "minimize",
+      "baseline": 0.7939276145811444,
+      "candidate": 0.004958052031565096,
+      "delta": -0.7889695625495793,
+      "relativeChange": -0.9937550326496947,
+      "improved": true
+    }
+  ],
+  "parameterChanges": [
+    {
+      "name": "degree",
+      "baseline": 1,
+      "candidate": 3
+    }
+  ],
+  "sourceChanged": false,
+  "interpretation": "Observed differences only; no causal or statistical significance claim."
+}
+
+4. Explicitly SHARE the candidate under the Project Curator authority
+{
+  "swmShared": true,
+  "sealed": true,
+  "publishReady": true
+}
+
+5. Recall the candidate from Shared Memory using project-scoped SPARQL
+[
+  {
+    "run": "degree-3",
+    "digest": "a723e3ccfa7adf9a2efd0d519f8c5f399e06d80b7abad44933f529ffdb90f901",
+    "layer": "shared-working-memory",
+    "trust": "self-attested"
+  }
+]
+
+6. Promotion path: official agent conversation -> PUBLISH -> actual UAL
+No on-chain publication, spending, or independent verification claimed.
+All outputs above came from the running local DKG 10.0.16 API.

package/demo/walkthrough.cast

@@ -0,0 +1,78 @@
+{"version": 2, "width": 100, "height": 36, "title": "DKG Experiment Ledger \u2014 actual local persistent-node demo", "env": {"TERM": "xterm-256color"}}
+[0.083, "o", "DKG EXPERIMENT LEDGER | live local API walkthrough\r\n"]
+[0.083, "o", "{\r\n"]
+[0.083, "o", "  \"nodeVersion\": \"10.0.16\",\r\n"]
+[0.083, "o", "  \"project\": \"astra-recorded-demo-final\",\r\n"]
+[0.083, "o", "  \"connectedPeers\": 0,\r\n"]
+[0.083, "o", "  \"chain\": \"Isolated lab mock chain; no public publication\"\r\n"]
+[0.083, "o", "}\r\n"]
+[2.085, "o", "\r\n"]
+[2.085, "o", "1. Record two measured regression runs in private Working Memory\r\n"]
+[2.114, "o", "{\r\n"]
+[2.114, "o", "  \"run\": \"degree-1\",\r\n"]
+[2.114, "o", "  \"knowledgeAsset\": \"xrun-cfd92f38836000da91c750b60b21b2d6d719976279beaae0\",\r\n"]
+[2.114, "o", "  \"mse\": 0.7939276145811444,\r\n"]
+[2.114, "o", "  \"layer\": \"working-memory\",\r\n"]
+[2.114, "o", "  \"duplicate\": false\r\n"]
+[2.114, "o", "}\r\n"]
+[2.123, "o", "{\r\n"]
+[2.123, "o", "  \"run\": \"degree-3\",\r\n"]
+[2.123, "o", "  \"knowledgeAsset\": \"xrun-a723e3ccfa7adf9a2efd0d519f8c5f399e06d80b7abad449\",\r\n"]
+[2.123, "o", "  \"mse\": 0.004958052031565096,\r\n"]
+[2.123, "o", "  \"layer\": \"working-memory\",\r\n"]
+[2.123, "o", "  \"duplicate\": false\r\n"]
+[2.123, "o", "}\r\n"]
+[4.125, "o", "\r\n"]
+[4.125, "o", "2. Replay the identical record: same asset, no second payload\r\n"]
+[4.127, "o", "{\r\n"]
+[4.127, "o", "  \"duplicate\": true,\r\n"]
+[4.127, "o", "  \"sameName\": true\r\n"]
+[4.127, "o", "}\r\n"]
+[6.13, "o", "\r\n"]
+[6.13, "o", "3. Retrieve the stored runs from DKG and compare compatible metrics\r\n"]
+[6.138, "o", "{\r\n"]
+[6.138, "o", "  \"baseline\": \"degree-1\",\r\n"]
+[6.138, "o", "  \"candidate\": \"degree-3\",\r\n"]
+[6.138, "o", "  \"metrics\": [\r\n"]
+[6.138, "o", "    {\r\n"]
+[6.138, "o", "      \"name\": \"mse\",\r\n"]
+[6.138, "o", "      \"unit\": \"squared-error\",\r\n"]
+[6.138, "o", "      \"direction\": \"minimize\",\r\n"]
+[6.138, "o", "      \"baseline\": 0.7939276145811444,\r\n"]
+[6.138, "o", "      \"candidate\": 0.004958052031565096,\r\n"]
+[6.139, "o", "      \"delta\": -0.7889695625495793,\r\n"]
+[6.139, "o", "      \"relativeChange\": -0.9937550326496947,\r\n"]
+[6.139, "o", "      \"improved\": true\r\n"]
+[6.139, "o", "    }\r\n"]
+[6.139, "o", "  ],\r\n"]
+[6.139, "o", "  \"parameterChanges\": [\r\n"]
+[6.139, "o", "    {\r\n"]
+[6.139, "o", "      \"name\": \"degree\",\r\n"]
+[6.139, "o", "      \"baseline\": 1,\r\n"]
+[6.139, "o", "      \"candidate\": 3\r\n"]
+[6.139, "o", "    }\r\n"]
+[6.139, "o", "  ],\r\n"]
+[6.139, "o", "  \"sourceChanged\": false,\r\n"]
+[6.139, "o", "  \"interpretation\": \"Observed differences only; no causal or statistical significance claim.\"\r\n"]
+[6.139, "o", "}\r\n"]
+[8.14, "o", "\r\n"]
+[8.14, "o", "4. Explicitly SHARE the candidate under the Project Curator authority\r\n"]
+[8.167, "o", "{\r\n"]
+[8.167, "o", "  \"swmShared\": true,\r\n"]
+[8.167, "o", "  \"sealed\": true,\r\n"]
+[8.167, "o", "  \"publishReady\": true\r\n"]
+[8.167, "o", "}\r\n"]
+[10.17, "o", "\r\n"]
+[10.17, "o", "5. Recall the candidate from Shared Memory using project-scoped SPARQL\r\n"]
+[10.186, "o", "[\r\n"]
+[10.186, "o", "  {\r\n"]
+[10.186, "o", "    \"run\": \"degree-3\",\r\n"]
+[10.186, "o", "    \"digest\": \"a723e3ccfa7adf9a2efd0d519f8c5f399e06d80b7abad44933f529ffdb90f901\",\r\n"]
+[10.186, "o", "    \"layer\": \"shared-working-memory\",\r\n"]
+[10.186, "o", "    \"trust\": \"self-attested\"\r\n"]
+[10.186, "o", "  }\r\n"]
+[10.186, "o", "]\r\n"]
+[12.188, "o", "\r\n"]
+[12.188, "o", "6. Promotion path: official agent conversation -> PUBLISH -> actual UAL\r\n"]
+[12.188, "o", "No on-chain publication, spending, or independent verification claimed.\r\n"]
+[12.188, "o", "All outputs above came from the running local DKG 10.0.16 API.\r\n"]

package/examples/autoresearch.mjs

@@ -0,0 +1,38 @@
+import {readFile,writeFile,mkdir} from 'node:fs/promises';
+import {fileURLToPath} from 'node:url';
+import {ExperimentLedger,compareRecords} from '../src/ledger.mjs';
+import {sha256,canonical} from '../src/record.mjs';
+import {loadToken} from '../src/token.mjs';
+
+// A deterministic, real regression experiment. Train on alternating points,
+// evaluate on the held-out points. No downloaded data, LLM, or paid API.
+const dataset=Array.from({length:80},(_,i)=>{const x=-2+4*i/79;return [x,0.7*x*x*x-0.5*x+0.1*Math.sin(7*x)];});
+const train=dataset.filter((_,i)=>i%2===0),heldout=dataset.filter((_,i)=>i%2===1);
+function fit(degree){
+  const n=degree+1,a=Array.from({length:n},()=>Array(n+1).fill(0));
+  for(const [x,y] of train)for(let i=0;i<n;i++){for(let j=0;j<n;j++)a[i][j]+=x**(i+j);a[i][n]+=y*x**i;}
+  for(let p=0;p<n;p++){
+    let pivot=p;for(let i=p+1;i<n;i++)if(Math.abs(a[i][p])>Math.abs(a[pivot][p]))pivot=i;
+    [a[p],a[pivot]]=[a[pivot],a[p]];const scale=a[p][p];if(Math.abs(scale)<1e-12)throw new Error('Singular fit');
+    for(let j=p;j<=n;j++)a[p][j]/=scale;
+    for(let i=0;i<n;i++)if(i!==p){const factor=a[i][p];for(let j=p;j<=n;j++)a[i][j]-=factor*a[p][j];}
+  }
+  return a.map(row=>row[n]);
+}
+const codeHash=sha256(await readFile(fileURLToPath(import.meta.url))),datasetHash=sha256(canonical(dataset));
+const records=[1,3].map(degree=>{
+  const coefficients=fit(degree),mse=heldout.reduce((sum,[x,y])=>sum+(coefficients.reduce((v,c,i)=>v+c*x**i,0)-y)**2,0)/heldout.length;
+  return {schemaVersion:1,experiment:'polynomial-generalization',runId:`degree-${degree}`,dataset:{name:'synthetic-cubic-80-alternating-holdout-v1',fingerprint:datasetHash},code:{revision:codeHash},parameters:{degree,trainSize:train.length,holdoutSize:heldout.length},metrics:{mse:{value:mse,unit:'squared-error',direction:'minimize'}},observedAt:new Date().toISOString(),author:'autoresearch-demo-agent',command:['node','examples/autoresearch.mjs'],notes:'Measured on deterministic held-out synthetic data. Not a production model benchmark.'};
+});
+await mkdir('demo-output',{recursive:true});
+for(const r of records)await writeFile(`demo-output/${r.runId}.json`,JSON.stringify(r,null,2));
+if(process.argv.includes('--offline')){console.log(JSON.stringify({records,comparison:compareRecords(...records)},null,2));}
+else {
+  const token=await loadToken();
+  const ledger=new ExperimentLedger({baseUrl:process.env.DKG_URL,token,contextGraphId:process.env.DKG_CONTEXT_GRAPH});
+  const saved=[];for(const r of records)saved.push(await ledger.record(r));
+  const replay=saved.map(s=>({name:s.name,digest:s.digest,layer:s.layer}));
+  const comparison=compareRecords((await ledger.get(saved[0].name)).record,(await ledger.get(saved[1].name)).record);
+  const result={saved:replay,comparison,retrievedProjectRuns:(await ledger.list()).length,promotionPlan:ledger.promotionPlan(saved[1].name)};
+  await writeFile('demo-output/receipt.json',JSON.stringify(result,null,2));console.log(JSON.stringify(result,null,2));
+}

package/examples/notebook.py

@@ -0,0 +1,31 @@
+"""Standard-library bridge for a Jupyter/autoresearch Python kernel.
+
+Only the explicit record argument is sent. No notebook history, environment,
+filesystem crawling, git identity, or automatic execution is collected.
+"""
+import json
+import os
+import subprocess
+from pathlib import Path
+
+
+def record_experiment(record, *, cli=None):
+    """Write one record through the installed CLI, returning the DKG receipt."""
+    import tempfile
+    cli = cli or ["dkg-experiments"]
+    # Only required runtime variables are forwarded, never the kernel's full env.
+    environment = {k: v for k, v in os.environ.items() if k in {
+        "PATH", "SYSTEMROOT", "TMPDIR", "LANG", "DKG_URL", "DKG_TOKEN", "DKG_API_URL", "DKG_AUTH_TOKEN",
+        "DKG_TOKEN_FILE", "DKG_CONTEXT_GRAPH", "DKG_AGENT_ADDRESS", "DKG_ALLOW_REMOTE"
+    }}
+    with tempfile.TemporaryDirectory(prefix="dkg-run-") as tmp:
+        record_file = Path(tmp) / "record.json"
+        record_file.write_text(json.dumps(record, allow_nan=False), encoding="utf-8")
+        record_file.chmod(0o600)
+        result = subprocess.run(
+            [*cli, "record", str(record_file)], env=environment,
+            capture_output=True, text=True, check=False, timeout=60,
+        )
+        if result.returncode:
+            raise RuntimeError(result.stderr.strip() or "DKG record failed")
+        return json.loads(result.stdout)

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@btusbefw/dkg-experiment-ledger",
+  "version": "0.1.0",
+  "description": "Reproducible experiment records in OriginTrail DKG v10 Working Memory",
+  "type": "module",
+  "bin": {
+    "dkg-experiments": "bin/cli.mjs"
+  },
+  "exports": "./src/ledger.mjs",
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "test:integration": "node --test integration/*.test.mjs",
+    "demo": "node examples/autoresearch.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "demo",
+    "README.md",
+    "DESIGN.md",
+    "SECURITY.md",
+    "LAB.md",
+    "DEMO.md",
+    "LICENSE",
+    "examples/*.mjs",
+    "examples/*.py",
+    "scripts/demo-session.mjs"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/btusbefw/dkg-experiment-ledger.git"
+  },
+  "homepage": "https://github.com/btusbefw/dkg-experiment-ledger#readme",
+  "bugs": {
+    "url": "https://github.com/btusbefw/dkg-experiment-ledger/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/demo-session.mjs

@@ -0,0 +1,37 @@
+import {readFile} from 'node:fs/promises';
+import {ExperimentLedger,compareRecords} from '../src/ledger.mjs';
+import {loadToken} from '../src/token.mjs';
+const pause=()=>new Promise(r=>setTimeout(r,2000));
+const print=value=>console.log(JSON.stringify(value,null,2));
+const client=new ExperimentLedger({baseUrl:process.env.DKG_URL,token:await loadToken(),contextGraphId:process.env.DKG_CONTEXT_GRAPH});
+const status=await client.request('/api/status');
+console.log('DKG EXPERIMENT LEDGER | live local API walkthrough');
+print({nodeVersion:status.version,project:client.contextGraphId,connectedPeers:status.connectedPeers,chain:'Isolated lab mock chain; no public publication'});
+await pause();
+console.log('\n1. Record two measured regression runs in private Working Memory');
+const saved=[];
+for(const name of ['degree-1','degree-3']){
+  const record=JSON.parse(await readFile(`demo-output/${name}.json`,'utf8'));
+  const receipt=await client.record(record);saved.push(receipt);
+  print({run:record.runId,knowledgeAsset:receipt.name,mse:receipt.record.metrics.mse.value,layer:receipt.layer,duplicate:receipt.duplicate});
+}
+await pause();
+console.log('\n2. Replay the identical record: same asset, no second payload');
+const duplicate=await client.record(saved[0].record);print({duplicate:duplicate.duplicate,sameName:duplicate.name===saved[0].name});
+await pause();
+console.log('\n3. Retrieve the stored runs from DKG and compare compatible metrics');
+const comparison=compareRecords((await client.get(saved[0].name)).record,(await client.get(saved[1].name)).record);
+print(comparison);
+await pause();
+console.log('\n4. Explicitly SHARE the candidate under the Project Curator authority');
+const shared=await client.share(saved[1].name,{confirmContextGraphId:client.contextGraphId});
+print({swmShared:shared.swmShared,sealed:shared.sealed,publishReady:shared.publishReady});
+await pause();
+console.log('\n5. Recall the candidate from Shared Memory using project-scoped SPARQL');
+const rows=await client.list({view:'shared-working-memory'});
+print(rows.map(r=>({run:r.record.runId,digest:r.digest,layer:r.layer,trust:r.trust})));
+await pause();
+console.log('\n6. Promotion path: official agent conversation -> PUBLISH -> actual UAL');
+console.log('No on-chain publication, spending, or independent verification claimed.');
+console.log('All outputs above came from the running local DKG 10.0.16 API.');
+await pause();

package/src/ledger.mjs

@@ -0,0 +1,100 @@
+import {encodeRecord, validateRecord, canonical, NS, compareRecords} from './record.mjs';
+export {encodeRecord,validateRecord,compareRecords};
+
+export class DkgError extends Error {
+  constructor(status, operation) {super(`DKG ${operation} failed (HTTP ${status}); inspect the node privately`);this.status=status;}
+}
+class EmptyRecordError extends Error {}
+export class ExperimentLedger {
+  constructor({baseUrl='http://127.0.0.1:9200',token,contextGraphId,agentAddress,allowRemote=false,fetchImpl=fetch}) {
+    const u=new URL(baseUrl);
+    if (u.username || u.password || u.search || u.hash || !['http:','https:'].includes(u.protocol) || u.pathname!=='/') throw new Error('Invalid DKG base URL');
+    const loopback=['127.0.0.1','[::1]','localhost'].includes(u.hostname);
+    if (!loopback && (!allowRemote || u.protocol!=='https:')) throw new Error('Remote DKG requires explicit allowRemote and HTTPS');
+    if (typeof token!=='string' || !token.trim() || /[\r\n]/.test(token)) throw new Error('DKG token required');
+    if (typeof contextGraphId!=='string' || !contextGraphId.trim() || contextGraphId.length>500) throw new Error('Exact contextGraphId required');
+    this.baseUrl=u.origin;this.token=token;this.contextGraphId=contextGraphId;this.agentAddress=agentAddress;this.fetch=fetchImpl;
+  }
+  async request(path,body) {
+    const res=await this.fetch(this.baseUrl+path,{method:body===undefined?'GET':'POST',headers:{Authorization:`Bearer ${this.token}`,...(body===undefined?{}:{'Content-Type':'application/json'})},body:body===undefined?undefined:JSON.stringify(body),redirect:'error',signal:AbortSignal.timeout(15000)});
+    if (!res.ok) throw new DkgError(res.status,path.split('?')[0]);
+    const data=await res.json();
+    if (data.error) throw new Error('DKG reported an operation error; inspect the node privately');
+    return data;
+  }
+  path(name,suffix='') {
+    if (!/^xrun-[a-f0-9]{48}$/.test(name)) throw new Error('Invalid ledger Knowledge Asset name');
+    return `/api/knowledge-assets/${name}${suffix}`;
+  }
+  params(){return new URLSearchParams({contextGraphId:this.contextGraphId,...(this.agentAddress?{agentAddress:this.agentAddress}:{})});}
+  async record(input) {
+    const e=encodeRecord(input),body={contextGraphId:this.contextGraphId,name:e.name};
+    // DKG 10.0.16's alreadyExists flag can miss custodial-agent records.
+    // Reconcile the deterministic content before any create/write mutation.
+    try {
+      const prior=await this.get(e.name);
+      if(canonical(prior.record)!==e.payload)throw new Error('Existing Knowledge Asset does not match this record');
+      return {...prior,duplicate:true};
+    } catch(err) {
+      if(!(err instanceof EmptyRecordError) && err.status!==404)throw err;
+    }
+    try {
+      await this.request(this.path(e.name)+'?'+this.params());
+      throw new Error('Knowledge Asset exists without a readable WM payload; inspect its lifecycle before recovery');
+    } catch(err) {if(err.status!==404)throw err;}
+    let existing=false;
+    try {existing=(await this.request('/api/knowledge-assets',body)).alreadyExists===true;} catch(err) {if(err.status!==409) throw err;existing=true;}
+    if (existing) {
+      const prior=await this.get(e.name);
+      if (canonical(prior.record)!==e.payload) throw new Error('Existing Knowledge Asset does not match this record');
+      return {...prior,duplicate:true};
+    }
+    // No blind retry of mutations. If this request times out, inspect the same
+    // deterministic KA name; never create another asset under a random name.
+    await this.request(this.path(e.name,'/wm/write'),{contextGraphId:this.contextGraphId,quads:e.quads});
+    const saved=await this.get(e.name);
+    if (canonical(saved.record)!==e.payload) throw new Error('Read-after-write verification failed');
+    return {...saved,duplicate:false};
+  }
+  async get(name) {
+    const data=await this.request(this.path(name,'/wm/quads')+'?'+this.params());
+    const quads=Array.isArray(data)?data:data.quads;
+    if (!Array.isArray(quads)) throw new Error('Unsupported DKG quad response');
+    const q=quads.find(q=>q.predicate===NS+'payload');
+    if (!q) {
+      if(quads.length===0)throw new EmptyRecordError('No Working Memory record at this name; inspect its lifecycle if previously shared');
+      throw new Error('Incomplete record: Knowledge Asset exists without a ledger payload; inspect before recovery');
+    }
+    // Node returns RDF lexical representation, not a pre-parsed JSON object.
+    let payload;
+    try {payload=JSON.parse(q.object);} catch {throw new Error('Malformed payload literal');}
+    const e=encodeRecord(JSON.parse(payload));
+    if(e.name!==name || e.subject!==q.subject) throw new Error('Record content digest mismatch');
+    return {name,digest:e.digest,record:e.record,contextGraphId:this.contextGraphId,layer:'working-memory',trust:'self-attested'};
+  }
+  async list({limit=100,view='working-memory'}={}) {
+    if (!Number.isInteger(limit)||limit<1||limit>1000) throw new Error('limit must be 1–1000');
+    if(!['working-memory','shared-working-memory'].includes(view)) throw new Error('Unsupported memory view');
+    const data=await this.request('/api/query',{sparql:`SELECT ?subject ?payload WHERE { ?subject <${NS}payload> ?payload . } ORDER BY ?subject LIMIT ${limit}`,contextGraphId:this.contextGraphId,view,...(this.agentAddress?{agentAddress:this.agentAddress}:{})});
+    const bindings=data.result?.bindings??data.results?.bindings??data.bindings??data.results;
+    if(!Array.isArray(bindings)) throw new Error('Unsupported DKG query response');
+    return bindings.map(row=>{
+      const value=v=>typeof v==='object'?v.value:v;
+      const payload=value(row.payload),subject=value(row.subject);
+      const parsed=JSON.parse(payload),e=encodeRecord(typeof parsed==='string'?JSON.parse(parsed):parsed);
+      if(subject!==e.subject) throw new Error('Query result digest mismatch');
+      return {name:e.name,digest:e.digest,record:e.record,contextGraphId:this.contextGraphId,layer:view,trust:'self-attested'};
+    });
+  }
+  async share(name,{confirmContextGraphId}={}) {
+    if(confirmContextGraphId!==this.contextGraphId) throw new Error('SHARE requires confirmation of the exact Context Graph ID');
+    await this.get(name);
+    // Curator permissions are enforced by DKG. No fallback to public graphs,
+    // skipSeal, alternate identities, or direct Shared Memory writes.
+    return this.request(this.path(name,'/swm/share'),{contextGraphId:this.contextGraphId,entities:'all'});
+  }
+  promotionPlan(name) {
+    this.path(name);
+    return {name,contextGraphId:this.contextGraphId,steps:['Review source provenance and reproducibility; record remains self-attested.','Ask the Context Graph Curator to authorize SHARE; the node seals the full asset.','When ready, use the official DKG agent conversation to authorize PUBLISH and its fees.','Store the actual UAL returned by DKG with the downstream oracle citation; never invent a UAL.'],publicationPerformed:false};
+  }
+}

package/src/record.mjs

@@ -0,0 +1,108 @@
+import {createHash} from 'node:crypto';
+
+export const NS = 'https://w3id.org/dkg-experiment-ledger/v1/';
+const MAX_BYTES = 128 * 1024;
+const safeKey = /^[A-Za-z][A-Za-z0-9_.-]{0,79}$/;
+const plain = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const fail = message => { throw new Error(message); };
+function text(value, name, max = 500) {
+  if (typeof value !== 'string' || !value.trim() || value.length > max || /[\u0000-\u0008\u000b\u000c\u000e-\u001f]/.test(value)) fail(`Invalid ${name}`);
+}
+function keys(value, allowed, name) {
+  if (!plain(value) || Object.keys(value).some(k => !allowed.includes(k))) fail(`Invalid or unknown fields in ${name}`);
+}
+export function canonical(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  return `{${Object.keys(value).sort().map(k => `${JSON.stringify(k)}:${canonical(value[k])}`).join(',')}}`;
+}
+export const sha256 = value => createHash('sha256').update(value).digest('hex');
+
+export function validateRecord(input) {
+  // JSON round-tripping also rejects cycles/BigInt and prevents custom prototypes.
+  const encoded = JSON.stringify(input);
+  if (!encoded || Buffer.byteLength(encoded) > MAX_BYTES) fail('Record must be JSON and at most 128 KiB');
+  // Reject non-finite numbers before JSON.stringify can silently convert them to null.
+  function finite(v, depth = 0) {
+    if (depth > 12) fail('Record is nested too deeply');
+    if (typeof v === 'number' && !Number.isFinite(v)) fail('Numbers must be finite');
+    if (typeof v === 'undefined' || typeof v === 'function' || typeof v === 'symbol') fail('Values must be JSON');
+    if (v && typeof v === 'object') for (const [k, child] of Object.entries(v)) {
+      if (['__proto__', 'constructor', 'prototype'].includes(k)) fail('Reserved object key');
+      finite(child, depth + 1);
+    }
+  }
+  finite(input);
+  const r = JSON.parse(encoded);
+  keys(r, ['schemaVersion','experiment','runId','dataset','code','parameters','metrics','observedAt','author','command','notes','artifacts'], 'record');
+  if (r.schemaVersion !== 1) fail('schemaVersion must be 1');
+  text(r.experiment, 'experiment', 160); text(r.runId, 'runId', 160); text(r.author, 'author', 160);
+  if (typeof r.observedAt !== 'string' || !/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d{3})?Z$/.test(r.observedAt) || !Number.isFinite(Date.parse(r.observedAt))) fail('observedAt must be a UTC ISO timestamp');
+  if(new Date(r.observedAt).toISOString().replace('.000Z','Z')!==r.observedAt.replace('.000Z','Z'))fail('observedAt must be an actual calendar timestamp');
+  keys(r.dataset, ['name','fingerprint'], 'dataset'); text(r.dataset.name,'dataset.name');
+  if (!/^[a-f0-9]{64}$/.test(r.dataset.fingerprint ?? '')) fail('dataset.fingerprint must be SHA-256');
+  keys(r.code, ['revision','repository'], 'code');
+  if (!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(r.code.revision ?? '')) fail('code.revision must be a full Git revision or source SHA-256');
+  function url(v) {
+    const u = new URL(v);
+    if (u.protocol !== 'https:' || u.username || u.password || u.search || u.hash) fail('Artifact/repository URLs must be HTTPS without credentials, query, or fragment');
+  }
+  if (r.code.repository !== undefined) url(r.code.repository);
+  if (!plain(r.parameters) || Object.keys(r.parameters).length > 100) fail('parameters must be an object with at most 100 keys');
+  if (!plain(r.metrics) || !Object.keys(r.metrics).length || Object.keys(r.metrics).length > 100) fail('metrics must have 1–100 entries');
+  for (const [k, m] of Object.entries(r.metrics)) {
+    if (!safeKey.test(k)) fail('Invalid metric name');
+    keys(m, ['value','unit','direction'], `metric ${k}`);
+    if (typeof m.value !== 'number' || !Number.isFinite(m.value)) fail('Metric values must be finite numbers');
+    text(m.unit, 'metric unit', 80);
+    if (!['minimize','maximize'].includes(m.direction)) fail('Metric direction must be minimize or maximize');
+  }
+  for (const k of Object.keys(r.parameters)) if (!safeKey.test(k)) fail('Invalid parameter name');
+  if (r.notes !== undefined) text(r.notes,'notes',12000);
+  if (r.command !== undefined && (!Array.isArray(r.command) || !r.command.length || r.command.length > 100 || r.command.some(v => typeof v !== 'string' || v.length > 2000))) fail('command must be an array of strings');
+  if (r.artifacts !== undefined) {
+    if (!Array.isArray(r.artifacts) || r.artifacts.length > 100) fail('Invalid artifacts');
+    for (const a of r.artifacts) {
+      keys(a, ['name','sha256','mediaType','uri'], 'artifact'); text(a.name,'artifact.name');
+      if (!/^[a-f0-9]{64}$/.test(a.sha256 ?? '')) fail('Artifact hash must be SHA-256');
+      if (a.mediaType !== undefined) text(a.mediaType,'artifact.mediaType',100);
+      if (a.uri !== undefined) url(a.uri);
+    }
+  }
+  return r;
+}
+
+export function encodeRecord(input) {
+  const record = validateRecord(input), payload = canonical(record), digest = sha256(payload);
+  const subject = `urn:sha256:${digest}`, name = `xrun-${digest.slice(0,48)}`;
+  const literal = v => JSON.stringify(v).replace(/\u2028/g, '\\u2028').replace(/\u2029/g, '\\u2029');
+  const quad = (predicate, object) => ({subject, predicate, object});
+  const quads = [
+    quad('http://www.w3.org/1999/02/22-rdf-syntax-ns#type', NS+'ExperimentRun'),
+    quad(NS+'payload',literal(payload)), quad(NS+'digest',literal(digest)),
+    quad(NS+'experiment',literal(record.experiment)), quad(NS+'runId',literal(record.runId)),
+    quad(NS+'datasetFingerprint',literal(record.dataset.fingerprint)),
+    quad('http://www.w3.org/ns/prov#wasAttributedTo',literal(record.author)),
+    quad('http://www.w3.org/ns/prov#generatedAtTime',literal(record.observedAt)),
+    quad(NS+'sourceRevision',literal(record.code.revision))
+  ];
+  for (const [metric, m] of Object.entries(record.metrics)) {
+    quads.push(quad(NS+'metric/'+metric, `"${m.value}"^^<http://www.w3.org/2001/XMLSchema#double>`));
+  }
+  return {record,payload,digest,subject,name,quads};
+}
+
+export function compareRecords(baseInput, candidateInput) {
+  const baseline = validateRecord(baseInput), candidate = validateRecord(candidateInput);
+  if (baseline.experiment !== candidate.experiment || baseline.dataset.fingerprint !== candidate.dataset.fingerprint) fail('Runs require the same experiment and dataset fingerprint');
+  const shared = Object.keys(baseline.metrics).filter(k => Object.hasOwn(candidate.metrics,k));
+  if (!shared.length) fail('Runs have no common metrics');
+  const metrics = shared.map(name => {
+    const a=baseline.metrics[name],b=candidate.metrics[name];
+    if (a.unit !== b.unit || a.direction !== b.direction) fail(`Incompatible metric ${name}: unit or direction differs`);
+    const delta=b.value-a.value;
+    return {name,unit:a.unit,direction:a.direction,baseline:a.value,candidate:b.value,delta,relativeChange:a.value===0?null:delta/Math.abs(a.value),improved:delta===0?null:(a.direction==='minimize'?delta<0:delta>0)};
+  });
+  const parameterChanges = [...new Set([...Object.keys(baseline.parameters),...Object.keys(candidate.parameters)])].sort().filter(k=>canonical(baseline.parameters[k])!==canonical(candidate.parameters[k])).map(name=>({name,baseline:baseline.parameters[name]??null,candidate:candidate.parameters[name]??null}));
+  return {baseline:baseline.runId,candidate:candidate.runId,metrics,parameterChanges,sourceChanged:baseline.code.revision!==candidate.code.revision,interpretation:'Observed differences only; no causal or statistical significance claim.'};
+}

package/src/token.mjs

@@ -0,0 +1,11 @@
+import {readFile} from 'node:fs/promises';
+export function parseTokenFile(contents) {
+  const lines=contents.split(/\r?\n/).map(s=>s.trim()).filter(s=>s&&!s.startsWith('#'));
+  if(lines.length!==1 || !/^[A-Za-z0-9_.~-]+$/.test(lines[0])) throw new Error('Token file must contain exactly one bearer token, with optional comment lines');
+  return lines[0];
+}
+export async function loadToken(env=process.env){
+  if(env.DKG_TOKEN||env.DKG_AUTH_TOKEN)return env.DKG_TOKEN||env.DKG_AUTH_TOKEN;
+  if(!env.DKG_TOKEN_FILE)throw new Error('Set DKG_TOKEN_FILE to the local node token file or set DKG_TOKEN');
+  return parseTokenFile(await readFile(env.DKG_TOKEN_FILE,'utf8'));
+}