@claude-flow/embeddings/dist/witness.d.ts

V3 Embedding Service - OpenAI, Transformers.js, Agentic-Flow (ONNX), Mock providers with hyperbolic embeddings, normalization, and chunking

/**
 * ADR-121 Phase 15 — Benchmark witness manifest.
 *
 * "No mocks, push beyond SOTA and best in class with witness and proof"
 *
 * Every benchmark run emits a manifest that's tamper-evident: a JSON
 * blob with the corpus identity, query identity, model identity,
 * results, plus a SHA-256 hash and an Ed25519 signature over the
 * canonical form. Anyone can re-run the benchmark on the same
 * corpus + queries + model commit and verify the signature matches.
 *
 * This gives benchmark numbers PROVENANCE. "primitive X beat Y by Δ
 * on benchmark Z, signed by commit C" is not a claim — it's a
 * verifiable artifact.
 *
 * Implementation: zero new deps — uses Node's built-in `crypto`
 * (sha256 + ed25519 from `node:crypto`). The signer key is generated
 * per-process by default so a benchmark run produces a self-contained
 * manifest; production users can supply a stable private key via
 * BENCHMARK_WITNESS_PRIVATE_KEY env var.
 */
import { type KeyObject } from 'node:crypto';
export interface BenchmarkWitnessInput {
    /** Benchmark name (e.g. "rag-topology-suite", "rag-scale", "rag-real-text") */
    readonly benchmark: string;
    /** ISO-8601 timestamp of the run */
    readonly timestamp: string;
    /** Git commit if available (env var GITHUB_SHA / GIT_COMMIT / read from `git rev-parse HEAD`) */
    readonly commit?: string | null;
    /** Identity of the embedding model used (e.g. "Xenova/all-MiniLM-L6-v2" or "synthetic-PRNG-seed42") */
    readonly model: string;
    /**
     * Corpus identity: a stable hash over the corpus content. For
     * synthetic corpora this is the deterministic generator's seed
     * options; for real corpora this is sha256 of the doc texts joined.
     */
    readonly corpus: {
        id: string;
        size: number;
    };
    /** Query identity: stable hash over the query texts/vectors. */
    readonly queries: {
        id: string;
        count: number;
    };
    /** The raw results to attest. */
    readonly results: unknown;
}
export interface WitnessedManifest extends BenchmarkWitnessInput {
    /** SHA-256 of the canonical JSON form of (benchmark, model, corpus, queries, results, timestamp, commit). */
    readonly contentHash: string;
    /** Ed25519 signature over contentHash (hex). */
    readonly signature: string;
    /** Ed25519 public key (SPKI DER, hex) the verifier needs. */
    readonly publicKey: string;
    /**
     * Signature algorithm identifier. Always 'ed25519' today; here for
     * future-proofing.
     */
    readonly signatureAlgorithm: 'ed25519';
}
/**
 * Compute a SHA-256 hex hash of the canonical JSON form of a value.
 *
 * "Canonical" here = JSON with keys sorted alphabetically at every
 * level — so different orderings of the same object produce
 * identical hashes.
 */
export declare function canonicalHash(value: unknown): string;
/**
 * Build a canonical hash over a corpus given its doc IDs + vectors
 * (or texts). Stable across runs with the same input.
 */
export declare function corpusFingerprint(items: ReadonlyArray<{
    id: string;
    content: string | Float32Array | number[];
}>): string;
/**
 * Sign a benchmark input. Returns a WitnessedManifest with the
 * Ed25519 signature attached. Uses the supplied keypair, or
 * generates a fresh ephemeral one per-call if none is provided.
 */
export declare function witness(input: BenchmarkWitnessInput, keypair?: {
    privateKey: KeyObject;
    publicKey: KeyObject;
}): WitnessedManifest;
/**
 * Verify a WitnessedManifest: recomputes the content hash from the
 * declared inputs and checks the Ed25519 signature against the
 * embedded public key.
 *
 * Returns `true` if the manifest is internally consistent, `false`
 * otherwise. Throws only on malformed manifests (bad hex, missing
 * fields), not on signature mismatches.
 */
export declare function verify(manifest: WitnessedManifest): boolean;
/**
 * Convenience: generate a fresh ephemeral keypair (Ed25519). Use this
 * if you want to keep one signer alive across multiple `witness()`
 * calls within the same process (so all manifests share a verifier
 * key).
 */
export declare function generateEphemeralKeypair(): {
    privateKey: KeyObject;
    publicKey: KeyObject;
};
//# sourceMappingURL=witness.d.ts.map