DICE API Documentation/com.embabel.dice.proposition/ProvenanceScanningSourceRevisionQueries

ProvenanceScanningSourceRevisionQueries

interface ProvenanceScanningSourceRevisionQueries : SourceRevisionQueryCapable, PropositionStore

The three source-revision finders answered by reading the context and filtering loaded provenance in memory.

Only a store whose context read carries every provenance entry may implement this. That is the condition the whole capability turns on: the in-memory and JSON-file stores keep entries on the proposition itself, so scanning them is exact. A backend with a lean context read implements SourceRevisionQueryCapable directly and pushes each predicate into its own query language.

Inheritors

InMemoryPropositionRepository

JsonFilePropositionRepository

Properties

supportsSourceRevisionQueries

open val supportsSourceRevisionQueries: Boolean

Whether this particular instance can actually answer these queries. Implementing the interface is a type-level promise; this is the runtime truth. A decorator that forwards to a backend it only discovers at construction time reports here whether the backend it got can answer. Callers check this before trusting an empty result.

Functions

addProvenance

open fun addProvenance(propositionId: String, entries: List<ProvenanceEntry>): Proposition?

Append provenance to a proposition (deduplicated); never removes existing entries.

clearProvenance

open fun clearProvenance(propositionId: String): Proposition?

Remove all provenance from a proposition.

count

abstract fun count(): Int

Get the total count of propositions.

open fun count(query: PropositionQuery): Int

Count the propositions matching query. The default materialises query's results and counts them; a backend that can count server-side (e.g. the graph store) overrides to avoid loading the rows just to size them.

delete

abstract fun delete(id: String): Boolean

Delete a proposition by ID.

findAll

abstract fun findAll(): List<Proposition>

Get all propositions.

findByContextId

open fun findByContextId(contextId: <Error class: unknown class>): List<Proposition>

Find propositions in the given context.

findByContextIdValue

open fun findByContextIdValue(contextIdValue: String): List<Proposition>

Java-friendly variant of findByContextId that accepts a plain string.

findByEntity

abstract fun findByEntity(entityIdentifier: <Error class: unknown class>): List<Proposition>

Find all propositions that mention a specific entity.

findByGrounding

abstract fun findByGrounding(chunkId: String): List<Proposition>

Find all propositions grounded by a specific chunk.

findById

abstract fun findById(id: String): Proposition?

Find a proposition by its ID.

findByMinLevel

abstract fun findByMinLevel(minLevel: Int): List<Proposition>

Find propositions at or above the specified abstraction level. Level 0 = raw observations, 1+ = abstractions.

findBySourceKey

open override fun findBySourceKey(contextIdValue: String, sourceKey: String): List<Proposition>

Find propositions in contextId with evidence from any revision of sourceKey.

findBySourceRevision

open override fun findBySourceRevision(contextIdValue: String, ref: SourceRevisionRef): List<Proposition>

Find propositions in contextId with evidence from exactly ref's source key and revision.

findByStatus

abstract fun findByStatus(status: PropositionStatus): List<Proposition>

Find all propositions with the given status.

findPinned

open fun findPinned(contextId: <Error class: unknown class>): List<Proposition>

All pinned propositions in contextId.

findRevisionlessBySourceLocator

open override fun findRevisionlessBySourceLocator(contextIdValue: String, locator: SourceLocator): List<Proposition>

Find propositions in contextId with revisionless evidence whose locator key equals locator's key.

keywordOverlap

open fun keywordOverlap(base: PropositionQuery, tokens: List<String>, limit: Int): List<Proposition>

Find propositions in base's scope whose text contains at least one of tokens (case-insensitive), ranked by how many distinct tokens each contains (descending), ties broken by base's ordering. At most limit results; empty tokens or non-positive limit returns nothing.

open fun pin(id: String): Proposition?

Pin a proposition so it resists reclamation: pinned propositions are skipped by the decay collector and the sweep policy, are decay-exempt in the default status policy, and are not auto-retired by contradiction resolution.

provenanceOf

open fun provenanceOf(propositionId: String): List<ProvenanceEntry>

The provenance entries of a proposition, or an empty list if it has none or does not exist.

query

open fun query(query: PropositionQuery): List<Proposition>

Query propositions using a PropositionQuery specification.

save

abstract fun save(proposition: Proposition): Proposition

Save a proposition. If a proposition with the same ID exists, it will be replaced.

saveAll

open fun saveAll(propositions: Collection<Proposition>)

Save multiple propositions.

saveAllReturningCanonical

open fun saveAllReturningCanonical(propositions: Collection<Proposition>): PropositionPersistenceResult

Save multiple propositions and report which stored proposition each one landed on.

setProvenance

open fun setProvenance(propositionId: String, entries: List<ProvenanceEntry>): Proposition?

Authoritatively set a proposition's provenance to exactly entries, removing any not listed.

touchAccessed

open fun touchAccessed(ids: Collection<String>)

Refresh Proposition.lastAccessed to now for ids — the read-side reinforcement that lets a DECAYING proposition's decay anchor (see Proposition.effectiveConfidenceAt) track actual use rather than only content edits. Best-effort and silent about unknown ids (a stale eager id that has since been deleted is not an error).

unpin

open fun unpin(id: String): Proposition?

Clear a proposition's pin, returning it to normal reclamation.