@parmanasystems/provenance

Immutable governance lineage and evidence. This package defines how input signals are documented with their source, trust level, and verification method; how those signals are hashed into a deterministic provenance summary; and how the full lineage chain is replayed or audited. It also provides the execution authority lifecycle (create → verify → consume), fail-closed execution gates, and portable proof bundles that can be independently verified without the runtime.

Public API

Signal provenance

/**
 * Attach provenance metadata to a raw signal map.
 * Wraps each signal value with a GovernedSignal envelope including
 * source, trust level, and verification method.
 */
function documentProvenance(
  signals: Record<string, unknown>,
  provenance: SignalProvenance
): GovernedSignalMap

/**
 * Convenience wrapper — document provenance for an account aggregator source.
 */
function accountAggregatorProvenance(
  signals: Record<string, unknown>,
  options: { provider: string; trustLevel?: TrustLevel }
): GovernedSignalMap

/**
 * Convenience wrapper — document provenance for a voice transcript source.
 */
function voiceTranscriptProvenance(
  signals: Record<string, unknown>,
  options: { transcriptionProvider: string; trustLevel?: TrustLevel }
): GovernedSignalMap

/**
 * Strip provenance envelopes and return raw signal values.
 * Use when passing a GovernedSignalMap to code that expects plain signals.
 */
function withoutProvenance(signals: GovernedSignalMap): Record<string, unknown>
function stripProvenance(signals: GovernedSignalMap): Record<string, unknown>

/**
 * Re-wrap plain signals with a provenance marker (minimal envelope).
 */
function withProvenance(
  signals: Record<string, unknown>,
  provenance: SignalProvenance
): GovernedSignalMap

/** Normalize a mixed signal map (plain or governed) to GovernedSignalMap. */
function normalizeGovernedSignals(signals: Record<string, unknown>): GovernedSignalMap

/** Extract plain signal values from a GovernedSignalMap. */
function extractSignalValues(signals: GovernedSignalMap): Record<string, unknown>

/** Extract the provenance envelope for each signal. */
function extractProvenanceMap(signals: GovernedSignalMap): Record<string, SignalProvenance>

Hashing

/** Hash an evidence payload to a hex string (deterministic). */
function hashEvidence(evidence: unknown): string
function hashEvidencePayload(evidence: unknown): string

/** Hash a provenance record to a hex string. */
function hashProvenance(provenance: SignalProvenance): string

/** Hash an aggregate summary of all signal provenances. */
function hashProvenanceSummary(signals: GovernedSignalMap): string

/** Hash the provenance of a single GovernedSignal. */
function hashSignalProvenance(signal: GovernedSignal): string

Validation

/**
 * Validate the structure and trust level of a GovernedSignalMap.
 * Returns ProvenanceValidationResult with per-signal pass/fail details.
 */
function validateProvenance(signals: GovernedSignalMap): ProvenanceValidationResult

interface ProvenanceValidationResult {
  valid: boolean;
  signals: Record<string, { valid: boolean; reason?: string }>;
}

Execution authority

/** Create a signed execution authority token. */
function createExecutionAuthority(options: {
  policyId: string;
  policyVersion: string;
  executionId: string;
  signer: Signer;
}): Promise<ExecutionAuthority>

/** Verify an execution authority's signature. */
function verifyExecutionAuthority(
  authority: ExecutionAuthority,
  publicKey: string
): Promise<ExecutionAuthorityVerification>

/** Hash an execution authority for lineage. */
function hashExecutionAuthority(authority: ExecutionAuthority): string

/**
 * Consume an execution authority (mark it used in the consumption store).
 * Throws if already consumed.
 */
async function consumeExecutionAuthority(
  authority: ExecutionAuthority,
  store: AuthorityConsumptionStore
): Promise<AuthorityConsumptionRecord>

function verifyAuthorityConsumption(
  record: AuthorityConsumptionRecord,
  store: AuthorityConsumptionStore
): Promise<ConsumptionVerificationResult>

Lineage

function createLineageEvent(input: { executionId: string; [key: string]: unknown }): LineageEvent
function verifyLineageChain(events: LineageEvent[]): boolean
async function replayLineage(events: LineageEvent[]): Promise<ReplayResult>

Proof bundles

/** Create a portable proof bundle for independent offline verification. */
async function createGovernanceProofBundle(options: {
  attestation: ExecutionAttestation;
  signals: GovernedSignalMap;
  signer: Signer;
}): Promise<GovernanceProofBundle>

/** Verify a governance proof bundle offline. */
async function verifyGovernanceProofBundle(
  bundle: GovernanceProofBundle,
  publicKey: string
): Promise<IndependentVerificationResult>

/** Independent verification without any Parmana runtime dependency. */
async function verifyGovernanceProof(
  bundle: GovernanceProofBundle,
  publicKey: string
): Promise<IndependentVerificationResult>

Audit

function buildAuditTimeline(events: AuditEvent[]): AuditTimeline
function hashAuditEvent(event: AuditEvent): string
function generateAuditReport(timeline: AuditTimeline): GovernanceAuditReport

Persistence stores

class InMemoryConsumptionStore implements AuthorityConsumptionStore { }
class RedisConsumptionStore    implements AuthorityConsumptionStore {
  constructor(redisUrl: string)
}
class PostgresLineageStore     implements LineagePersistenceStore {
  constructor(connectionString: string)
}

interface ExecutionConsumptionStore { /* extends AuthorityConsumptionStore */ }
interface LineagePersistenceStore   { /* persists LineageEvent objects */ }
interface GovernanceProofStore      { /* persists GovernanceProofBundle objects */ }

Core types

interface GovernedSignal {
  value: unknown;
  provenance: SignalProvenance;
}

type GovernedSignalMap = Record<string, GovernedSignal>

interface SignalProvenance {
  sourceType: SourceType;
  trustLevel: TrustLevel;
  verificationMethod: VerificationMethod;
  sourceAttestation?: SourceAttestation;
}

type SourceType = "account_aggregator" | "voice_transcript" | "direct_input" | string
type TrustLevel = "high" | "medium" | "low" | string
type VerificationMethod = "cryptographic" | "institutional" | "self_reported" | string

Environment variables

RedisConsumptionStore reads a Redis URL from its constructor argument, not from env. PostgresLineageStore similarly takes a connection string. No implicit env reads.

Package wiring

@parmanasystems/provenance depends on @parmanasystems/canonical. normalizeGovernedSignals is called inside executeFromSignals in @parmanasystems/execution-runtime to normalize mixed signal maps before policy evaluation. @parmanasystems/core re-exports hashEvidence, hashProvenance, validateProvenance, documentProvenance, the convenience wrappers, and all signal types.