{"_id":"@btusbefw/dkg-experiment-ledger","_rev":"2-36e34370616ef1246b18beab74008d30","name":"@btusbefw/dkg-experiment-ledger","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@btusbefw/dkg-experiment-ledger","version":"0.1.0","license":"MIT","_id":"@btusbefw/dkg-experiment-ledger@0.1.0","maintainers":[{"name":"btusbefw","email":"dev@dbrx.fr"}],"homepage":"https://github.com/btusbefw/dkg-experiment-ledger#readme","bugs":{"url":"https://github.com/btusbefw/dkg-experiment-ledger/issues"},"bin":{"dkg-experiments":"bin/cli.mjs"},"dist":{"shasum":"140a81bcdf59aabea6cfd3c25d20b9b67e2f0e09","tarball":"https://registry.npmjs.org/@btusbefw/dkg-experiment-ledger/-/dkg-experiment-ledger-0.1.0.tgz","fileCount":16,"integrity":"sha512-HIV7sZ52AIcIG0Nj6GBv1ohiz7QF05636xqlI723dpjaBBAmEAWO1UW/yKC3eKQRcor2h9jtHCEhT8WqI5wWOA==","signatures":[{"sig":"MEUCIQD2btIlQuJa0AbKuSv8Ny2gfWEOAckyEeaZ+rjjDqeYbwIgMRcfZtPVhJHYtitFvXDEducPcN4Teh81EXCt1GlCEjA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":51631},"type":"module","engines":{"node":">=22"},"exports":"./src/ledger.mjs","gitHead":"f9bd425a30ef85ed698c47f03c76da28ae37e790","scripts":{"demo":"node examples/autoresearch.mjs","test":"node --test test/*.test.mjs","test:integration":"node --test integration/*.test.mjs"},"_npmUser":{"name":"btusbefw","email":"dev@dbrx.fr"},"repository":{"url":"git+https://github.com/btusbefw/dkg-experiment-ledger.git","type":"git"},"_npmVersion":"11.12.1","description":"Reproducible experiment records in OriginTrail DKG v10 Working Memory","directories":{},"_nodeVersion":"25.6.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/dkg-experiment-ledger_0.1.0_1789024080611_0.5263443101591976","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"_id":"@btusbefw/dkg-experiment-ledger@0.1.1","bin":{"dkg-experiments":"bin/cli.mjs"},"bugs":{"url":"https://github.com/btusbefw/dkg-experiment-ledger/issues"},"dist":{"shasum":"389ebf5052d660e2d662e447fdd1eff07cd461a5","tarball":"https://registry.npmjs.org/@btusbefw/dkg-experiment-ledger/-/dkg-experiment-ledger-0.1.1.tgz","fileCount":16,"integrity":"sha512-ViKdfMaOSbiasuC9BX85by0NwYQMvs0BOXgKSYy7xBrxKNZSWF9oiTz0heaLREI+RZu2mquCPN76dfEJ6Vjvfg==","signatures":[{"sig":"MEUCICYZrao3eDxD6I2x+tBHozLEIE9DqufBzJloX9VaeVMsAiEAgUX7tl0e8eQKYjEZaeG4wCmFZZS3SM3gUTK3QltICZc=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDK/En5yVq2FsgiayMaKKqaafjS/6U3piOrdy6vKomBJAIgU8dZ8iWovXDSAQCpgw5KK2iuxnVDvcEvEgYL4KWyWiY="}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@btusbefw%2fdkg-experiment-ledger@0.1.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":51751},"name":"@btusbefw/dkg-experiment-ledger","type":"module","engines":{"node":">=22"},"exports":"./src/ledger.mjs","gitHead":"49d0e394d18a630e096316ab9635e8b757dc81f0","license":"MIT","scripts":{"demo":"node examples/autoresearch.mjs","test":"node --test test/*.test.mjs","test:integration":"node --test integration/*.test.mjs"},"version":"0.1.1","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:c98d125a-7e73-49f0-94b3-59c9acaf38b0"}},"homepage":"https://github.com/btusbefw/dkg-experiment-ledger#readme","repository":{"url":"git+https://github.com/btusbefw/dkg-experiment-ledger.git","type":"git"},"_npmVersion":"11.19.1","description":"Reproducible experiment records in OriginTrail DKG v10 Working Memory","directories":{},"maintainers":[{"name":"btusbefw","email":"dev@dbrx.fr"}],"_nodeVersion":"24.20.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/dkg-experiment-ledger_0.1.1_1789024733868_0.671014160759924"}}},"time":{"created":"2026-09-10T07:08:00.434Z","modified":"2026-09-10T07:18:54.350Z","0.1.0":"2026-09-10T07:08:00.787Z","0.1.1":"2026-09-10T07:18:53.968Z"},"bugs":{"url":"https://github.com/btusbefw/dkg-experiment-ledger/issues"},"license":"MIT","homepage":"https://github.com/btusbefw/dkg-experiment-ledger#readme","repository":{"url":"git+https://github.com/btusbefw/dkg-experiment-ledger.git","type":"git"},"description":"Reproducible experiment records in OriginTrail DKG v10 Working Memory","maintainers":[{"name":"btusbefw","email":"dev@dbrx.fr"}],"readme":"# DKG Experiment Ledger\n\nRecord 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.\n\n## Run locally\n\nRequires 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.\n\n```sh\nexport DKG_URL=http://127.0.0.1:9200\nexport DKG_TOKEN_FILE=/path/to/your/local-agent.token\nexport DKG_CONTEXT_GRAPH=your-exact-project-id\nnode examples/autoresearch.mjs --offline\nnode bin/cli.mjs validate demo-output/degree-1.json\nnode bin/cli.mjs record demo-output/degree-1.json\nnode bin/cli.mjs list\n```\n\nThe 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.\n\nInstall the public package with `npm install --global @btusbefw/dkg-experiment-ledger`.\n\nAfter 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.\n\n## Record contract\n\nSee the generated `demo-output/degree-1.json` for a complete example. Required fields:\n\n- `schemaVersion: 1`, `experiment`, `runId`, `observedAt` (UTC ISO), `author` (your agent identifier).\n- `dataset: {name, fingerprint}`. The SHA-256 fingerprint should identify the effective evaluation data, split, and preprocessing protocol; use the same convention throughout an experiment.\n- `code: {revision}`: a full Git SHA or source SHA-256. Optional `repository` must be a clean HTTPS URL.\n- `parameters`: JSON object. `metrics`: named `{value, unit, direction}` entries; direction is `minimize` or `maximize`.\n- Optional `command` (an argument array, stored only), `notes`, and `artifacts` (name, SHA-256, optional media type and clean HTTPS URI).\n\nOnly 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.\n\n## Recall, compare, and promote\n\n```sh\ndkg-experiments show xrun-<48-hex-name>\ndkg-experiments compare xrun-<baseline> xrun-<candidate>\ndkg-experiments promotion-plan xrun-<candidate>\ndkg-experiments share xrun-<candidate> your-exact-project-id\ndkg-experiments list shared-working-memory\n```\n\n`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.\n\nComparisons 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.\n\n`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.\n\n## Notebook integration\n\nImport `record_experiment` from `examples/notebook.py` into a Jupyter kernel or ordinary Python program:\n\n```python\nreceipt = record_experiment(my_explicit_record,\n    cli=[\"node\", \"/absolute/path/to/bin/cli.mjs\"])\nprint(receipt[\"name\"], receipt[\"digest\"])\n```\n\nThe 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.\n\n## Validation\n\n```sh\nnpm test\n# Only against the isolated lab node described in LAB.md:\nDKG_TEST_LOCAL=1 npm run test:integration\n```\n\nThe 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.\n\nMaintainer: [btusbefw](https://github.com/btusbefw). Report reproducible problems through the [issue tracker](https://github.com/btusbefw/dkg-experiment-ledger/issues).\n","readmeFilename":"README.md"}