Provenance<V> enum

Defines the Causal Accountability, Audit Trail, and Operational Intent of a Pulse.

Provenance documents the transient lifecycle of a signal. While Ontology describes the "Static Scene" (what a node is), Provenance provides the dynamic Chain of Custody (who, why, and how) for every stimulus traversing the reactive tissue.

This metadata is utilised by the Policy Enforcement Point (PEP) to perform Capability-Based Access Control (CBAC) and ensure Execution Traceability.

When to use

• You rarely interact with Provenance directly. Instead, use the PulseContext factories like PulseContext.userAction, PulseContext.aiInference, or PulseContext.regulated. These factories populate the relevant provenance dimensions for you.
• If you need a custom pulse context, you can create one with the PulseContext constructor, passing the appropriate dimensions manually. But in most cases, the pre‑defined factories are sufficient.

How it works

• Each Provenance dimension is a typed key that holds a value of type V.
• Some dimensions are Static Pillars (evolvable: false) – they are immutable and cannot be changed once a pulse is created. These anchor the pulse's identity (e.g., actor, traceId).
• Others are Fluid Boundaries (evolvable: true) – they can be refined as the pulse moves through the graph (e.g., reason, confidence, priority).
• The framework uses these dimensions during validation (via TestCell) and auditing (via the causal trace).

Non‑obvious

• The Provenance.evolvable flag is enforced by the engine – you cannot change a static pillar via evolve().
• The compose and evolve static methods are used internally by PulseContext to build contexts. You rarely call them directly.
• The integrity dimension is a cryptographic checksum of the payload, ensuring tamper‑proofing – it's automatically handled by the framework.

Example: Creating a Pulse with Provenance

final pulse = Pulse.governed<int>(
  payload: 42,
  context: PulseContext.userAction(
    actor: 'admin_01',
    reason: 'Manual override',
    priority: 80,
  ),
);

final fullProvenance = PulseContext.fromEntries([
  // --- Static Pillars (Non-Evolvable Identity) ---
  Provenance.actor.entry('Autonomous_Optimizer_7'), // Identity Source
  Provenance.traceId.entry('trace_882-xf'),        // Causal Anchor
  Provenance.parentTraceId.entry('trace_881-xf'),  // Lineage Link

  // --- Fluid Boundaries (Evolvable Intent) ---
  Provenance.reason.entry('Resource_Saturation_Detected'), // Rationale
  Provenance.purpose.entry('TOPOLOGY_REFRESH'),           // Mission Category
  Provenance.strategy.entry(ReasoningStrategy.probabilistic), // Logic Pedigree
  Provenance.confidence.entry(0.85),                        // Trust Scalar
  Provenance.priority.entry(40),                           // Urgency Rank
  Provenance.compliance.entry('GDPR_EU_DATA_LOCALITY'),    // Safety Policy
]);

See also:

• PulseContext – the runtime container for these dimensions.
• Ontology – the static structural identity of a node.
• Mandate – the authority profile of a deputy.

Inheritance

• Object
• Enum
• Provenance

Implemented types

• Governance<V>

Mixed-in types

• GovernanceMixin<Provenance<V>, V>

Available extensions

• EnumName

Values

actor → const Provenance<String>

The unique identifier for the Principal, Service, or AI Agent responsible for initiating or transforming this Pulse.

The actor (of type String) establishes the Identity Layer of the signal. It is the primary key used by the system to look up the Mandate or permissions associated with the source of the stimulus.

When to use

This is set automatically by the PulseContext factories. You rarely need to set it manually.

How it works

During the mutual authorization handshake, the actor is scrutinised to verify that the source has the required clearance and authority.

Non‑obvious

• This is a static pillar – once set, it cannot be changed.
• The framework uses this for identity‑based access control.

Examples

• 'user_8823_admin' – direct manual intervention.
• 'service_cache_manager' – background maintenance.
• 'agent_thermal_optimizer_4' – AI instance.

const Provenance<String>(false)

reason → const Provenance<String>

A semantic justification explaining why the specific Pulse was created or transformed.

While purpose describes the high-level mission, reason provides the Immediate Causal Logic behind a mutation. It is a critical component of the system's Audit Dimension.

When to use

This is set automatically by factories, but you can override it when evolving a pulse.

How it works

The reason is used for Explainable AI (XAI) and is inspected by integrity gates to ensure the mutation is justified.

Non‑obvious

• This is an evolvable dimension – you can refine it as the pulse traverses the graph.
• It should be human‑readable for audit purposes.

Examples

• 'Clamping signal to [0,1] range to prevent somatic overflow.'
• `'Refactoring topology to meet current Resource constraints.'

const Provenance<String>(true)

purpose → const Provenance<String>

The strategic operational mission or Mission Category that governs the life‑cycle and routing of a Pulse.

While reason explains the immediate "why", purpose defines the Strategic Intent. It acts as a high‑level classifier used by the framework for traffic shaping, priority queueing, and somatic shedding.

When to use

This is set by the factories (e.g., PulseContext.homeostasis sets it to 'SYSTEM_MAINTENANCE'). You rarely set it manually.

How it works

Receptors can use purpose to filter or prioritise pulses – e.g., dropping analytics pulses when under load.

Non‑obvious

• This is evolvable – a pulse can be refined to a more specific purpose as it moves through the graph.
• It is compared against the cell's Ontology.domains during validation.

Examples

• 'SYSTEM_MAINTENANCE' – background grooming.
• 'USER_TRANSACTION' – user‑driven updates.
• 'FORENSIC_AUDIT' – observational pulses.

const Provenance<String>(true)

strategy → const Provenance<ReasoningStrategy>

The specific Reasoning Strategy or algorithmic pedigree used to generate or transform this Pulse.

The strategy defines the Methodology of Intent. It allows the framework to evaluate the reliability and source logic of a signal.

When to use

This is set by factories (e.g., aiInference sets it to probabilistic).

How it works

Integrity gates can reject pulses that use an unacceptable strategy, e.g., a cell might only accept deterministic signals.

Non‑obvious

• This is evolvable – a probabilistic signal can be upgraded to deterministic after validation.
• The strategy influences trust and auditing.

Examples

• ReasoningStrategy.deterministic – hard‑coded business rules.
• ReasoningStrategy.probabilistic – AI/ML generated.
• ReasoningStrategy.manual – human intervention.

const Provenance<ReasoningStrategy>(true)

confidence → const Provenance<double>

A numerical value (0.0 to 1.0) representing the Reliability Estimate of the pulse's payload.

confidence represents the "Certainty Weight" of the stimulus. It is the primary metric for Probabilistic Homeostasis.

When to use

This is set by AI‑related factories (e.g., aiInference).

How it works

TestCells can require a minimum confidence; low‑confidence signals may be routed for supervised approval.

Non‑obvious

• This is evolvable – confidence can be adjusted as more evidence is gathered.
• The default is 1.0 for deterministic and manual signals.

Examples

• 0.65 – uncertain AI suggestion.
• 0.98 – high‑confidence sensor fusion.

const Provenance<double>(true)

priority → const Provenance<int>

The Execution Urgency (0-100) assigned to the signal.

priority defines the scheduling importance of the Pulse. It determines the signal's position in the dispatch queue.

When to use

Set this when you need to control the order of processing. Most factories set it appropriately (e.g., userAction sets 60).

How it works

The dispatcher uses this to prioritise pulses; higher numbers leapfrog lower ones. The framework uses standard tiers: background (0-20), routine (21-50), high (51-80), critical (81-95), emergency (96-100).

Non‑obvious

• This is evolvable – priority can be promoted or demoted.
• The default is 21 (routine) if not set.

Examples

• 10 – background telemetry.
• 90 – critical system recovery.

Priority Tiers:

• 0-20: Background (telemetry, maintenance)
• 21-50: Routine (standard operations)
• 51-80: High (user interactions)
• 81-95: Critical (system safety)
• 96-100: Emergency (system recovery)

const Provenance<int>(true)

compliance → const Provenance<String>

The Regulatory Framework or legal protocol that governs the handling of this Pulse.

compliance provides the Legal Context for the stimulus. It dictates how the payload must be treated, stored, and transmitted.

When to use

Use this when the pulse must adhere to specific regulations (GDPR, HIPAA, etc.). The regulated factory sets it automatically.

How it works

Integrity gates can block pulses that lack required compliance markers.

Non‑obvious

• This is a static pillar – cannot be changed once set.
• The framework enforces compliance constraints automatically.

Examples

• 'GDPR' – triggers redaction of PII.
• 'PCI-DSS' – forces encryption and full audit.

const Provenance<String>(false)

sensitivity → const Provenance<Sensitivity>

The Information Classification tier of the payload.

sensitivity establishes the Privacy Perimeter for the signal. It informs the framework how to handle data at rest, in transit, and during observability.

When to use

This is set by factories (e.g., userAction defaults to public; regulated sets confidential).

How it works

The framework uses sensitivity to enforce redaction, encryption, and access control.

Non‑obvious

• This is a static pillar – cannot be changed.
• Higher sensitivity requires higher clearance to process.

Examples

• Sensitivity.public – safe for logging.
• Sensitivity.secret – restricted to secure enclaves.

const Provenance<Sensitivity>(false)

auditLevel → const Provenance<AuditLevel>

The specific Observability Density applied to this pulse.

auditLevel defines the Forensic Fidelity of the signal. It determines how much causal metadata and payload information is captured.

When to use

This is set by factories – e.g., regulated sets full.

How it works

The framework uses this to decide what to log and trace.

Non‑obvious

• This is evolvable – a pulse can be promoted to full on demand.
• Higher audit levels may impact performance.

Examples

• AuditLevel.none – high‑frequency telemetry, no logging.
• AuditLevel.full – forensic‑grade trace.

const Provenance<AuditLevel>(true)

traceId → const Provenance<String>

The globally unique Causal Anchor for tracing a signal across distributed execution paths.

traceId establishes the Deterministic Lineage of a pulse. It ensures that every state change can be correlated back to its origin.

When to use

This is automatically generated by the framework. You never set it manually.

How it works

The traceId is used for deduplication and to link parent/child pulses.

Non‑obvious

• This is a static pillar – immutable.
• It is generated as a UUID v4.

const Provenance<String>(false)

parentTraceId → const Provenance<String>

The traceId of the Pulse that logically preceded or triggered this one.

parentTraceId establishes the Causal Link between pulses, enabling multi‑step reasoning chains.

When to use

This is automatically set when you evolve a pulse.

How it works

The framework uses this to link a child pulse to its parent, preserving the full causal chain.

Non‑obvious

• This is a static pillar – immutable.
• If a parent pulse is invalidated, children may also be invalidated.

const Provenance<String>(false)

integrity → const Provenance<String>

The cryptographic or checksum‑based Verification Signature ensuring the pulse's payload has not been tampered with.

integrity provides the Immutable Shield for the pulse.

When to use

This is automatically computed by the framework. You never set it.

How it works

The framework hashes the payload and stores the hash; on receipt, the hash is re‑computed and compared.

Non‑obvious

• This is a static pillar – immutable.
• If the payload changes, the integrity signature must be re‑generated.

Examples

• sha256:e3b0c442... – standard hash.
• rsa-sig:a92f81... – signed with a private key.

const Provenance<String>(false)

Properties

evolvable → bool

Indicates whether this Provenance Dimension is a structural invariant or a dynamic operational attribute.

final

hashCode → int

The hash code for this object.

no setter, inherited

index → int

A numeric identifier for the enumerated value.

no setter, inherited

name → String

Available on Enum, provided by the EnumName extension

The name of the enum value.

no setter

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

Methods

entry(V value) → GovernanceEntry<Provenance<V>, V>

Creates a strongly-typed GovernanceEntry for this governance dimension.

inherited

isType(Object value) → bool

Validates if the provided value matches the expected type V.

inherited

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

toString() → String

A string representation of this object.

inherited

Operators

operator ==(Object other) → bool

The equality operator.

inherited

Static Methods

compose(GovernanceEntry<Governance, dynamic>? resolver(Provenance dimension)) → Iterable<GovernanceEntry<Governance, dynamic>>

Generates a comprehensive Signal Manifest by synthesising a value for every defined dimension in the Provenance ontology.

evolve(GovernanceEntry<Governance, dynamic>? resolver(Provenance dimension)) → Iterable<GovernanceEntry<Governance, dynamic>>

Syntheses a Specialised Signal Extension by resolving only the fluid dimensions of the Provenance ontology.

Constants

values → const List<Provenance>

A constant List of the values in this enum, in order of their declaration.