DICE API Documentation/com.embabel.dice.spi

Package-level declarations

Types

object AlwaysContradictionDetector : ConflictDetector

Conservative default ConflictDetector that classifies every clash as a ConflictType.Contradiction. With it installed, conflict classification is a no-op refinement and behaviour matches a reviser with no conflict typing.

AuthorityResolver

interface AuthorityResolver

Policy SPI: resolves the AuthorityTier of a proposition's source.

AuthorityTier

enum AuthorityTier : Enum<AuthorityTier>

How authoritative the source backing a proposition is.

AuthorityWeightedTrustScorer

open class AuthorityWeightedTrustScorer constructor(weights: Map<AuthorityTier, Double> = DEFAULT_WEIGHTS, unknownScore: Double = DEFAULT_UNKNOWN_SCORE) : TrustScorer

A TrustScorer that scores a proposition purely by the authority of its source: more authoritative tiers get a higher trust score. This is the natural step up from NeutralTrustScorer for consumers who want "trust the source" behaviour without writing their own model.

CandidatePair

data class CandidatePair(val anchor: Proposition, val member: Proposition, val proposalScore: Double? = null)

One proposed pair of propositions worth scoring.

CandidatePairSource

fun interface CandidatePairSource

Proposes candidate pairs worth scoring, e.g. by vector clustering.

CollapseUndoCommand

data class CollapseUndoCommand(val contextId: <Error class: unknown class>, val survivorId: String, val retiredId: String)

Names one collapse to undo, inside the context that owns it.

CollapseUndoConfigurationException

class CollapseUndoConfigurationException(message: String) : IllegalStateException

The undo was wired with something it cannot work from: no audit records to authorize it, or a proposition store that cannot subtract evidence atomically. Both are configuration mistakes, and both are thrown before the undo reads or writes anything.

CollapseUndoContextMismatchException

class CollapseUndoContextMismatchException(val commandedContextId: <Error class: unknown class>, val propositionId: String, val actualContextId: <Error class: unknown class>) : IllegalArgumentException

A proposition the undo was told to touch lives in a different context. Thrown before any write, so the other context's graph is left exactly as it was.

CollapseUndoResult

data class CollapseUndoResult(val survivor: Proposition, val restored: Proposition)

The result of undoing one collapse: the survivor with that member's exclusive evidence subtracted, and the member restored to its prior status.

CollectorCandidateEdge

data class CollectorCandidateEdge(val anchorId: String, val memberId: String, val aggregateScore: Double, val vetoed: Boolean, val signals: List<CollectorSignalScore>)

A scored, aggregated edge between two propositions across all signals.

CollectorComponent

data class CollectorComponent(val componentId: String, val memberIds: List<String>)

A connected component of propositions the collector formed from surviving edges.

CollectorDecision

data class CollectorDecision(val runId: String, val componentId: String, val survivorId: String, val action: String, val retired: List<RetiredProposition>)

Records everything needed to reverse a collapse: the run it belongs to, the chosen survivor, and for each retired proposition its prior status plus the grounding, provenance and source ids that a merging sweep folded onto the survivor. The runId lets a caller find the candidate edges (and their per-signal scores) behind this decision via CollectorTraceQuery.findEdgesByRun.

CollectorSignalScore

data class CollectorSignalScore(val signal: String, val score: Double, val weight: Double = 1.0, val veto: Boolean = false, val explanation: String? = null, val evidenceRef: String? = null)

One signal's score for one pair.

CollectorSignalScorer

fun interface CollectorSignalScorer

Scores one proposed pair on a single signal. Returning null means abstain — the signal is left out of the blend. Inject dependencies via the constructor, not per call.

CollectorTraceQuery

interface CollectorTraceQuery

The read side of the collector trace: look up what a run decided, or explain why one proposition was collapsed. Callers that only need to inspect trace data (e.g. an admin API) should depend on this instead of the concrete storage implementation.

CollectorTraceStore

interface CollectorTraceStore

Persists the collector's inspectable decision trace under a run id. In-memory and graph-backed implementations both satisfy this.

ConflictDetector

fun interface ConflictDetector

Policy SPI: classifies the ConflictType between an incoming proposition and an existing one it appears to contradict.

ConflictType

sealed interface ConflictType

Classifies the nature of a conflict between an incoming proposition and an existing one that it appears to contradict.

ConnectedComponentsFinder

interface ConnectedComponentsFinder

Groups proposition ids into connected components from scored, non-vetoed edges.

DecayStatusPolicy

class DecayStatusPolicy(val stalenessThreshold: Double = 0.1, val recoveryThreshold: Double = 0.2, val kMultiplier: Double = 2.0, val importanceWeight: Double = 0.0, val reinforceWeight: Double = 0.0) : StatusTransitionPolicy

Default StatusTransitionPolicy: transitions ACTIVE → STALE when a proposition's decayed utility drops below stalenessThreshold, and STALE → ACTIVE when utility recovers above recoveryThreshold.

DriftQuarantineKeys

object DriftQuarantineKeys

Metadata keys drift quarantine writes onto a proposition, alongside the shared com.embabel.dice.common.DiceMetadataKeys.QUARANTINE_REASON.

DriftQuarantinePolicy

interface DriftQuarantinePolicy

Decides which propositions a schema change has stranded, and flags them.

DriftSweepCapable

interface DriftSweepCapable

The store-side operations a host needs to act on a drift check: find the propositions a schema change could have stranded, quarantine them, and let them back out again.

FixedAuthorityResolver

class FixedAuthorityResolver constructor(tier: AuthorityTier = AuthorityTier.UNKNOWN) : AuthorityResolver

AuthorityResolver that always returns a single configured tier, ignoring the proposition entirely. Useful when every proposition in a context shares the same provenance, or as a deterministic stand-in.

InMemoryCollectorTraceStore

class InMemoryCollectorTraceStore : CollectorTraceStore, CollectorTraceQuery

A thread-safe, in-process CollectorTraceStore that keeps everything in concurrent maps keyed by run id. Good for tests and single-node setups that don't need the trace to survive a restart; a graph-backed store can implement the same interface for durability.

InMemoryConnectedComponentsFinder

class InMemoryConnectedComponentsFinder : ConnectedComponentsFinder

An in-memory ConnectedComponentsFinder that unions the endpoints of every non-vetoed edge with a simple union-find, then reports each id's component as its root.

MarkReason

sealed interface MarkReason

Why a proposition was marked for collection by a CollectorStrategy.

MentionTypeDriftQuarantinePolicy

class MentionTypeDriftQuarantinePolicy : DriftQuarantinePolicy

The shipped DriftQuarantinePolicy: quarantine a proposition when one of its entity mentions names a type the schema change made lossy. Lossy means the change can strand data that was already extracted:

MergingSweepPolicy

class MergingSweepPolicy constructor(targetStatus: PropositionStatus = PropositionStatus.STALE) : SweepPolicy

Sweep policy for the dedup path: collapse near-duplicates by merging the loser's evidence onto its survivor rather than just flipping it STALE.

NeutralTrustScorer

object NeutralTrustScorer : TrustScorer

Default TrustScorer that trusts every proposition equally, returning 1.0 regardless of the proposition, its authority tier, or any conflict.

PropositionMark

data class PropositionMark constructor(val propositionId: String, val reason: MarkReason, val strategyName: String, val at: Instant = Instant.now())

An immutable record that a CollectorStrategy has marked a proposition for collection.

PropositionStoreDriftSweep

class PropositionStoreDriftSweep constructor(propositions: PropositionStore, listener: DiceEventListener = DiceEventListener.DEV_NULL) : DriftSweepCapable

The reference DriftSweepCapable: a working sweep over any PropositionStore, and the executable statement of what the contract means.

QuarantineDecision

sealed interface QuarantineDecision

What a policy decided about one Proposition.

QuarantineResult

data class QuarantineResult constructor(val conforming: List<QuarantineDecision.Conforming>, val quarantined: List<QuarantineDecision.Quarantined>, val alreadyQuarantined: List<QuarantineDecision.AlreadyQuarantined> = emptyList(), val protected: List<QuarantineDecision.Protected> = emptyList())

What a whole sweep decided, with one decision per proposition it was given.

RetiredProposition

data class RetiredProposition constructor(val propositionId: String, val priorStatus: PropositionStatus, val foldedGrounding: List<String> = emptyList(), val foldedProvenanceRefs: List<String> = emptyList(), val foldedSourceIds: List<String> = emptyList(), val foldedProvenanceEvidenceKeys: List<String> = emptyList())

One proposition that was folded into a survivor, and what a merging sweep would carry over from it (grounding, provenance and source ids) so the fold can be undone.

StatusTransitionPolicy

fun interface StatusTransitionPolicy

Policy SPI: determines whether a proposition should transition lifecycle status.

StatusTransitionSweepPolicy

class StatusTransitionSweepPolicy constructor(targetStatus: PropositionStatus = PropositionStatus.STALE) : SweepPolicy

Default SweepPolicy: non-destructive and safe for pinned propositions.

StructuralAuthorityResolver

class StructuralAuthorityResolver constructor(tierByLocatorKind: Map<KClass<out SourceLocator>, AuthorityTier> = DEFAULT_MAP) : AuthorityResolver

AuthorityResolver that maps a proposition's grounding locator kinds to authority tiers via tierByLocatorKind.

SweepAction

sealed interface SweepAction

What the sweep phase should do with a marked proposition, as decided by a SweepPolicy.

SweepPolicy

fun interface SweepPolicy

The "sweep" half of the mark-and-sweep collector: given a proposition and its marks, decides what should actually happen to it as a SweepAction.

TemporalConflictDetector

class TemporalConflictDetector constructor(evolvingPredicates: Set<String> = DEFAULT_EVOLVING_PREDICATES) : ConflictDetector

ConflictDetector that distinguishes world progression from genuine contradiction using the proposition predicate and temporal recency.

TrustScorer

fun interface TrustScorer

Policy SPI: assigns a trust score to a proposition.

Functions

undoSingleCollapse

fun undoSingleCollapse(command: CollapseUndoCommand, traceQuery: CollectorTraceQuery, propositions: PropositionStore, collectorRecords: CollectorRecordStore?): CollapseUndoResult?

Undoes ONE collapse — a single survivor/retired-member pair — without disturbing the run's other collapses. This is the targeted counterpart to a run-level undo: restore exactly the member named by CollapseUndoCommand.retiredId to its prior status, and subtract only what it (no other still-retired member of the same collapse) contributed to the survivor.

fun ~~undoSingleCollapse~~(traceQuery: CollectorTraceQuery, propositions: PropositionStore, survivorId: String, retiredId: String): CollapseUndoResult?

The undo as it shipped before the command form: no context to check ownership against and no audit records to confirm the collapse was applied, so it restores the member and subtracts its folded refs on the trace's word alone. Kept so a caller compiled against the four-argument form keeps working; the guarded form above is what new code should call, and this one goes in the next minor release.