{"_id":"@chaoscypherinc/ccx-format","_rev":"2-9245708827c31a8e0b45198eeec7f19d","name":"@chaoscypherinc/ccx-format","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@chaoscypherinc/ccx-format","version":"0.1.0","keywords":["ccx","knowledge-graph","json-ld","rdf","graphrag","package-format"],"author":{"name":"Denis MacPherson"},"license":"Apache-2.0","_id":"@chaoscypherinc/ccx-format@0.1.0","maintainers":[{"name":"dmacpherson","email":"denismacpherson@gmail.com"}],"homepage":"https://chaoscypher.com","bugs":{"url":"https://github.com/chaoscypherinc/ccx/issues"},"dist":{"shasum":"a6fed130a0931251cd50997e17672395640974bb","tarball":"https://registry.npmjs.org/@chaoscypherinc/ccx-format/-/ccx-format-0.1.0.tgz","fileCount":7,"integrity":"sha512-mFpUjJn9PghxYS931r4v6dh/71shYISYb3RJO8b4NGtEc+/V0a2Mt7SgbA8XdtVSPNdrEW7XcdZnl2Q0dp0Bfg==","signatures":[{"sig":"MEYCIQCFzL2dVgDyeObRl60tMFvHMf24xL9aLXGhHQrB4/EBggIhAOaFhf/zCp9VpGns9yeDB0yD4TT7cgY5ZNhhkt5pRXSr","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@chaoscypherinc%2fccx-format@0.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":85124},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"gitHead":"48e6502e48f2a6d32391a7a20bda0f6595742417","scripts":{"test":"vitest run","build":"tsup","pretest":"npm run sync-schema","prebuild":"npm run sync-schema","typecheck":"tsc --noEmit","sync-schema":"node scripts/sync-schema.mjs","prepublishOnly":"npm run build"},"_npmUser":{"name":"dmacpherson","email":"denismacpherson@gmail.com"},"repository":{"url":"git+https://github.com/chaoscypherinc/ccx.git","type":"git","directory":"js"},"_npmVersion":"10.8.2","description":"Reference TypeScript reader/validator for CCX (Chaos Cypher eXchange) — the open, JSON-LD-native knowledge-graph package format.","directories":{},"_nodeVersion":"20.20.2","dependencies":{"ajv":"^8.17.1","jszip":"^3.10.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.3.0","vitest":"^2.1.0","typescript":"^5.6.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/ccx-format_0.1.0_1782147173084_0.06182053737597104","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@chaoscypherinc/ccx-format","version":"0.1.1","description":"Reference TypeScript reader/validator for CCX (Chaos Cypher eXchange) — the open, JSON-LD-native knowledge-graph package format.","license":"Apache-2.0","author":{"name":"Denis MacPherson"},"type":"module","publishConfig":{"access":"public"},"engines":{"node":">=18"},"main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"keywords":["ccx","knowledge-graph","json-ld","rdf","graphrag","package-format"],"repository":{"type":"git","url":"git+https://github.com/chaoscypherinc/ccx.git","directory":"js"},"homepage":"https://chaoscypher.com","scripts":{"sync-schema":"node scripts/sync-schema.mjs","prebuild":"npm run sync-schema","build":"tsup","smoke":"node scripts/smoke-esm.mjs","pretest":"npm run sync-schema","test":"vitest run","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"dependencies":{"jszip":"^3.10.1","ajv":"^8.17.1"},"devDependencies":{"typescript":"^5.6.0","tsup":"^8.3.0","vitest":"^2.1.0","@types/node":"^20.0.0"},"_id":"@chaoscypherinc/ccx-format@0.1.1","gitHead":"e852cf7a8ab8ce5b1f02efa3527e3c7598345d2c","bugs":{"url":"https://github.com/chaoscypherinc/ccx/issues"},"_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-QbffOHydjnfwojCvQhvtrZv6hobkdmMDbgkgXQr5LxPD0nLoCq7ZCejsxGxvPN5PxOSpcgfGdZvgJbBfq5B0SA==","shasum":"75d53a8b5f0492298b99863008ac8e4f59e11ba2","tarball":"https://registry.npmjs.org/@chaoscypherinc/ccx-format/-/ccx-format-0.1.1.tgz","fileCount":7,"unpackedSize":85173,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@chaoscypherinc%2fccx-format@0.1.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDWzG0Vc+GkGjZ7hh3WownyUOC4AQMxjNS4YOOeiVz9JAIhAPpp3zrKUpqRFMrdsDYu1eFn5BmGOdgn9tmwhhrNOOut"}]},"_npmUser":{"name":"dmacpherson","email":"denismacpherson@gmail.com"},"directories":{},"maintainers":[{"name":"dmacpherson","email":"denismacpherson@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ccx-format_0.1.1_1782153754367_0.6548971379942969"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-22T16:52:52.909Z","modified":"2026-06-22T18:42:34.803Z","0.1.0":"2026-06-22T16:52:53.219Z","0.1.1":"2026-06-22T18:42:34.525Z"},"bugs":{"url":"https://github.com/chaoscypherinc/ccx/issues"},"author":{"name":"Denis MacPherson"},"license":"Apache-2.0","homepage":"https://chaoscypher.com","keywords":["ccx","knowledge-graph","json-ld","rdf","graphrag","package-format"],"repository":{"type":"git","url":"git+https://github.com/chaoscypherinc/ccx.git","directory":"js"},"description":"Reference TypeScript reader/validator for CCX (Chaos Cypher eXchange) — the open, JSON-LD-native knowledge-graph package format.","maintainers":[{"name":"dmacpherson","email":"denismacpherson@gmail.com"}],"readme":"# @chaoscypherinc/ccx-format\n\n[![npm](https://img.shields.io/npm/v/@chaoscypherinc/ccx-format.svg)](https://www.npmjs.com/package/@chaoscypherinc/ccx-format)\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/chaoscypherinc/ccx/blob/main/LICENSE)\n\nThe Apache-2.0 **TypeScript reference reader** for **CCX 3.0** — parity-tested\nagainst the Python `ccx-format` reader on the shared conformance fixtures.\n\n**CCX (Chaos Cypher eXchange)** is an open, JSON-LD-native package format for\n**portable, source-backed knowledge graphs**. A `.ccx` file is a ZIP that is,\nsemantically, an **RDF Dataset**: a `knowledge` default graph plus any number of\nnamespaced named graphs. It carries entities, relationships, the **sources** they\nwere extracted from, **citations** linking claims back to those sources, and —\noptionally — vector **embeddings**, **SHACL shapes**, and cryptographic\n**signatures**, all in a single file you can move between tools without losing\nprovenance.\n\nThis package is a **reader/validator** (read + validate + inspect). To *write*\n`.ccx` files, use the Python `ccx-format` package (`pip install ccx-format`).\n\n```bash\nnpm i @chaoscypherinc/ccx-format\n```\n\nNode ≥ 18. Self-contained: the only runtime dependencies are `jszip` and `ajv`.\n\n---\n\n## Read and validate a package\n\n```ts\nimport { readFileSync } from \"node:fs\";\nimport { openPackage } from \"@chaoscypherinc/ccx-format\";\n\n// openPackage takes raw bytes (Uint8Array). Read the file however you like.\nconst pkg = await openPackage(readFileSync(\"people.ccx\"));\n\nconst report = await pkg.validate();\nconsole.log(report.ok, report.classes); // true [ 'core', 'sources' ]\nfor (const w of report.warnings) console.log(\"warn:\", w);\n\n// Manifest metadata\nconst m = pkg.manifest;\nconsole.log(m.name, m.packageVersion, m.license); // demo/people 1.0.0 CC-BY-4.0\n\n// Walk the graphs (the default `knowledge` graph + any named graphs)\nfor (const g of await pkg.graphDocuments()) {\n  console.log(g.namespace, g.name, g.role); // ccx knowledge default\n  const doc = g.doc as { \"@graph\"?: { \"@id\": string; \"@type\"?: unknown }[] };\n  for (const node of doc[\"@graph\"] ?? []) {\n    console.log(node[\"@id\"], node[\"@type\"]);\n  }\n}\n\n// Sources + chunks (Core + Sources packages)\nfor (const rec of await pkg.sources()) {\n  console.log(rec[\"@id\"], rec[\"@type\"]); // ccx:Source / ccx:Chunk\n}\n```\n\nHigher-class accessors:\n\n```ts\nawait pkg.context();           // the parsed bundled JSON-LD @context\nawait pkg.shapes();            // the shapes.ttl text, or null\npkg.embeddings();              // embedding descriptors from the manifest\nawait pkg.verifySignatures();  // offline, fail-closed ed25519 verification\nawait pkg.assetBytes(path);    // raw bytes of a content-addressed asset\nawait pkg.computeStats();      // { nodeCount, edgeCount, sourceCount }\n```\n\n### Error handling\n\n`openPackage` rejects unsafe archives (zip bomb, path traversal, symlink escape,\nbad ZIP) and missing/malformed/schema-invalid manifests. Recoverable validation\nproblems are reported on `report.errors` (with `report.ok === false`) rather than\nthrown.\n\n```ts\nimport { openPackage, CcxValidationError, CcxSecurityError } from \"@chaoscypherinc/ccx-format\";\n\ntry {\n  const pkg = await openPackage(bytes);\n  const report = await pkg.validate();\n  if (!report.ok) console.error(\"invalid:\", report.errors);\n} catch (err) {\n  if (err instanceof CcxSecurityError) console.error(\"unsafe package:\", err.message);\n  else if (err instanceof CcxValidationError) console.error(\"malformed package:\", err.message);\n  else throw err;\n}\n```\n\n---\n\n## Conformance classes\n\n`validate()` reports every class a package satisfies in `report.classes`. They\nare **independent capabilities**, not a linear ladder — a package can be\n`core + sources` without embeddings or shapes.\n\n| Class | A package qualifies when it… |\n|---|---|\n| **core** | is a well-formed `.ccx`: STORED `mimetype`, schema-valid `manifest.json`, every declared file present with matching SHA-256 + SHA-512, a `knowledge` default graph, no remote `@context`. |\n| **sources** | adds `sources.jsonl` with source/chunk records (offset selectors into a text asset, or inline content) and citations aligned to W3C Web Annotation. |\n| **embeddings** | declares embedding descriptors (model + dimensions), optionally with content-addressed vector sidecars. |\n| **shapes** | ships a valid SHACL `shapes.ttl`. |\n| **signed** | ships ≥ 1 detached signature over the manifest (ed25519, verified offline). |\n\nFull normative requirements (RFC-2119) are in the\n[specification](https://github.com/chaoscypherinc/ccx/tree/main/spec).\n\n---\n\n## Security & hardening\n\nThe reader is built to consume **untrusted** packages:\n\n- **No network at read time** — remote `@context` / `@import` references are\n  rejected; the bundled `context.jsonld` is authoritative.\n- **Decompression bounds** — entry-count, per-entry, and total-uncompressed\n  limits guard against zip-bombs.\n- **Path safety** — path traversal, absolute paths, and symlink entries are\n  rejected.\n- **Integrity** — every declared file's SHA-256 **and** SHA-512 are verified.\n- **Signatures** verify **offline** and **fail closed**; the signature `format`\n  field is crypto-agile, with post-quantum (ML-DSA / SLH-DSA) formats reserved.\n\n---\n\n## License\n\n**Apache-2.0.** This is the TypeScript reference reader for the CCX format, the\nsecond independent implementation alongside the Python `ccx-format` reader and\nverified against it on the shared conformance fixtures. CCX is an open, documented\nformat — there is no vendor lock-in, and a `.ccx` produced by any tool is readable\nby any conformant reader.\n\nIssues and discussion: <https://github.com/chaoscypherinc/ccx/issues>.\n","readmeFilename":"README.md"}