Crate knowledge_runtime 

knowledge-runtime

Hardened scaffold / bounded first-pass orchestration layer for semantic-memory.

This crate provides intent classification, route planning, entity resolution, result merging, and projection lifecycle tracking on top of semantic-memory.

Authority Model

This crate NEVER owns source truth. All facts, episodes, documents, and conversation messages live in semantic-memory. This crate owns only:

• Derived projections (entity registry, projection tracker)
• Query pipeline logic (classification, planning, merge)
• Observability traces

Deleting any projection forces recomputation but causes no data loss.

Query Pipeline

query text
  -> classify (QueryMode: semantic | entity | temporal | mixed)
  -> plan (RoutePlan with legs)
  -> execute (per-leg retrieval via semantic-memory adapter)
  -> merge (fuse duplicates with provenance, normalize, boost, rank, truncate)
  -> results + QueryTrace (including degradation warnings)

Implemented Now

• Rule-based intent classification: heuristic extraction of entity mentions (@name, "quoted"), temporal keywords, and mixed signals.
• Route planning: translates classified query modes into retrieval legs.
• Projection-backed retrieval for imported knowledge: imported claim, relation, and episode rows are queried directly through semantic-memory’s public projection APIs.
• Hybrid fallback where projection substrate is absent: namespace-only BM25/vector retrieval remains available when a supported projection route is unavailable for the queried leg.
• Entity search: scope-aware registry resolution plus bounded imported alias candidate expansion before fallback.
• Deterministic result merge with provenance fusion: duplicates across legs are fused (not discarded), retaining union of source legs and per-leg scores. Tie-breaking is three-tier: score > source leg count > lexicographic identity key. Multi-leg support gets a configurable score boost.
• Scope-aware entity registry: entities are partitioned by ScopeKey (namespace + domain + workspace_id + repo_id). Resolution falls back from narrow scope to namespace-only when needed, with fallback visible in results.
• Scope enforcement transparency: projection-backed routes enforce full scope directly. ScopePartiallyEnforced is emitted only when execution must fall back to namespace-only hybrid retrieval.
• Scope-aware code identity: code entity IDs include repo_id/workspace_id/namespace so the same qualified path in different repos yields different IDs.
• Projection lifecycle observability: health, staleness (time-based + explicit), invalidation by scope/kind/id, stale cause, and version metadata. The tracker currently emits Healthy, Stale, and Missing; reserved compatibility variants remain in the public enum but are not emitted by the tracker today.
• Import staleness detection: the runtime checks semantic-memory’s last import timestamp for the queried namespace and emits ProjectionImportStale warnings when data may be outdated. Import freshness is surfaced as a query warning today, not as a dedicated tracker health transition.
• Query traces with degradation warnings: unsupported temporal downgrade, partial scope enforcement on hybrid fallback, entity scope fallback, and import staleness are all surfaced in QueryTrace::warnings. Helper methods (is_degraded(), has_temporal_downgrade(), etc.) make warnings inspectable.
• Strict enforcement modes (KR-001/KR-002): strict_temporal and strict_scope config flags convert degradation warnings into hard errors for callers that require guaranteed temporal/scope semantics rather than best-effort.
• Rebuild driver interface (KR-003): the RebuildDriver trait provides a defined contract for external callers to drive projection rebuilds. The rebuild_stale convenience function polls the tracker and drives rebuilds automatically. The tracker remains observability-only.

Not Real Yet (Deferred)

• Range temporal expressions: projection-backed temporal execution is implemented for concrete as-of markers such as today, yesterday, last week, and this month. Range-style phrases such as before, after, since, and between still degrade explicitly.
• Namespace-only hybrid scope: semantic-memory hybrid search only pushes namespace. When runtime must use that path for a scoped query, the limitation is surfaced via QueryWarning::ScopePartiallyEnforced or RuntimeError::ScopeNotFullyEnforced.
• Projection persistence: the persist config flag is rejected at validation time. Durable runtime projections are not implemented in this crate today.
• Projection rebuild execution: the tracker is observability-only; it records build/failure events but does not schedule, execute, or retry rebuilds. External callers implement the RebuildDriver trait to drive actual rebuilds and report outcomes back to the tracker (KR-003).
• LLM-based intent classification: classifier is rule-based heuristic.
• Evidence handle external dereference: this layer does not resolve evidence handles against external stores.
• Advanced fuzzy entity resolution: bounded candidate expansion exists, but there is no embedding-based or graph-ML entity resolver.

Re-exports

pub use config::RuntimeConfig;

pub use error::RuntimeError;

pub use ids::ProjectionId;

pub use ids::ProjectionKind;

pub use runtime::EntityCacheHandle;

pub use runtime::KnowledgeRuntime;

pub use runtime::ProjectedPromotionState;

pub use runtime::ProjectedVerificationLifecycle;

pub use runtime::ProjectedVerificationSummary;

pub use entity::code_ids::CodeEntity;

pub use entity::code_ids::CodeEntityKind;

pub use entity::registry::Entity;

pub use entity::registry::EntityKind;

pub use entity::registry::EntityRegistry;

pub use entity::registry::MatchQuality;

pub use entity::registry::ResolveResult;

pub use evidence::support::AnswerBundle;

pub use evidence::support::EvidenceItem;

pub use evidence::support::EvidenceRelevance;

pub use evidence::support::SearchEvidenceBundle;

pub use obs::trace::ProjectionAction;

pub use obs::trace::ProjectionTrace;

pub use obs::trace::QueryTrace;

pub use obs::trace::QueryWarning;

pub use obs::trace::RuntimeQueryProvenanceV1;

pub use projection::lifecycle::InvalidationEvent;

pub use projection::lifecycle::ProjectionActionResult;

pub use projection::lifecycle::ProjectionHealth;

pub use projection::lifecycle::ProjectionMeta;

pub use projection::lifecycle::ProjectionTracker;

pub use projection::lifecycle::ProjectionVersion;

pub use projection::lifecycle::StaleCause;

pub use projection::rebuild::rebuild_stale;

pub use projection::rebuild::RebuildDriver;

pub use projection::rebuild::RebuildOutcome;

pub use query::classify::ClassifyResult;

pub use query::classify::QueryMode;

pub use query::merge::MergePolicy;

pub use query::merge::MergedItem;

pub use query::merge::MergedResults;

pub use query::route::LegFilter;

pub use query::route::RetrievalStrategy;

pub use query::route::RouteLeg;

pub use query::route::RoutePlan;

pub use temporal::claims::TemporalClaim;

pub use temporal::claims::TemporalContradictionStatus;

pub use views::CompiledObligationRuntimeViewV1;

pub use views::CompositionConflictRuntimeViewV1;

pub use views::ContinuityRuntimeViewV1;

pub use views::DelegationRuntimeViewV1;

pub use views::DeployabilityRuntimeViewV1;

pub use views::EffectRuntimeViewV1;

pub use views::EffectiveConstitutionViewV1;

pub use views::PolicyImpactDiffRuntimeViewV1;

Modules

adapters

config

entity

error

evidence

ids

obs

projection

query

runtime

temporal

views

Structs

EntityId

Opaque identifier for an entity (person, concept, code unit, etc.).

InferenceAdvisory

InferenceExplanation

RiskGateDecision

Scope

Multi-dimensional scope that bounds every runtime query and projection.

ScopeKey

Compact, hashable representation of all scope dimensions.