@inflexa-ai/prov-kernel

@inflexa-ai/prov-kernel is the Inflexa provenance format kernel. It carries the Inflexa PROV dialect: the document model (QName derivation, unify options, an injectable digest, and the appendLifecycleAction extension primitive), the lineage read model (deriveLineageModel, computeLineage, computeReachable, findFileEntity), the chain-hash and Ed25519 sign/verify primitives, the signed-attestation schema, and the actor and ref value types that the events carry. SPEC.md gives the exact wire format, sufficient for an independent implementation.

The package is a kernel, not a recorder. The three-layer rule divides the work:

• The harness observes. It reports facts: a run started, a command ran, a file appeared.
• The kernel represents. It turns each fact into PROV statements with deterministic identifiers, and it signs and verifies the result. The core event union (ProvEvent) and its apply function (applyProvEvent) live here: the event-to-statements mapping determines the document bytes, thus it is format.
• Hosts decide. Each host owns its recorder lifecycle, its emission policy, its storage, and its key custody. Core statements are produced only through applyProvEvent; a host maps its own extension events onto appendLifecycleAction, the QName derivations, and tsprov interop.

Thus the package deliberately does NOT contain a recorder (sink, flush, queue, CAS) or signer wiring. Those are host-owned.

The package runs in browser and server runtimes. No module imports a node:-prefixed module. The digest is the synchronous SHA-256 from the audited @noble/hashes package. The signature primitives use the Web Crypto API (globalThis.crypto). Thus a browser bundler resolves every import.

Use

npm install @inflexa-ai/prov-kernel

npm run build   # tsc -p tsconfig.json — emit dist/ from src/
bun test        # run the test suite (Node is the runtime; bun runs tests only)

import { createProvDocumentModel, applyProvEvent, PROV_UNIFY_OPTIONS, createKeypairSigner, buildAttestation, verifyAttestation } from "@inflexa-ai/prov-kernel";

const model = createProvDocumentModel(); // or inject a historical digest
const doc = model.freshDocument({ analysisId: "a1" });
applyProvEvent(model, doc, { type: "run_started", analysisId: "a1", actor, run: { runId: "r1", startedAtMs } });
const json = doc.unified(PROV_UNIFY_OPTIONS).serialize("json");

The digest that derives every QName suffix is injectable, because it is identity-load-bearing: a host with existing documents must inject its historical digest function, or its identifier space forks. The default digest is canonical for new documents.

License

Apache-2.0. See LICENSE and NOTICE.