Knowledge Platform — aggregate roots¶

Generated from the architecture model

This page is rendered from model/**/*.yaml by tools/docs_model during mkdocs build. Edit the YAML, not this page; hand-written design lives on the linked service, platform and plane pages.

Aggregate	Service	Root entity	Events	Tables
Artifact	ArtifactService	Artifact	ArtifactStored, ArtifactValidated, ArtifactSuperseded, ArtifactDeleted	Artifacts, LineageEdges, VersionChains
ContextSnapshot	ContextBuilderService	ContextSnapshot	ContextAssembled	ContextSnapshots, ContextItems
MemoryItem	MemoryPromotionService	MemoryItem	MemoryObserved, MemoryClassified, MemoryPromoted, MemoryArchived, SkillCandidateProposed	MemoryItems, ReviewDecisions, ConsentRecords
KnowledgeSource	KnowledgeIngestionService	KnowledgeSource	SourceRegistered, SourceStateChanged, SourceDeleted	KnowledgeSources, Collections
SourceSnapshot	KnowledgeIngestionService	SourceSnapshot	SourceSnapshotTaken, ChunksPublished, SnapshotFailed	SourceSnapshots, Documents, Chunks
RepositoryIndexSet	RepositoryIntelligenceService	RepositoryIndexSet	RepositoryIndexed, RepositoryIndexFailed	RepositoryIndexSets, Symbols, DependencyEdges, Ownership
IndexRevision	VectorMemoryService	IndexRevision	IndexRevisionReady, IndexRevisionRetired, IndexDegraded	IndexRevisions, IndexItems
GraphFact	VectorMemoryService	GraphFact	GraphFactsUpdated	GraphFacts
RetrievalQuery	VectorMemoryService	RetrievalQuery	RetrievalExecuted	RetrievalQueries

Artifact (ArtifactService)¶

An immutable content object addressed by hash with metadata, classification, access scope, producer (run, attempt, agent), inputs it derived from and the version chain it belongs to (artifact-v1).

Field	Type	Required	Description
`artifactId`	`guid`	yes
`tenantId`	`string`	yes
`projectId`	`string`	yes
`kind`	`enum:ArtifactKind`	yes
`name`	`string`	yes
`contentHash`	`hash`	yes
`contentRef`	`string`	yes	Blob reference in artifact-blob.
`sizeBytes`	`long`	yes
`mediaType`	`string`	yes
`classification`	`string`	yes
`accessScope`	`json`	yes	Who may read beyond the project scope.
`producerRunId`	`guid`	no
`producerAttemptId`	`guid`	no
`producerAgentId`	`string`	no
`chainId`	`guid`	yes	Version chain this artifact belongs to.
`versionInChain`	`int`	yes
`state`	`enum:ArtifactState`	yes
`validationRef`	`string`	no
`createdAt`	`datetime`	yes

Invariants

Content is immutable; a new content hash is a new artifact and a new version in its chain.
Every artifact produced by a run records the run, attempt and agent; every derived artifact records its inputs as lineage edges.
Deleting an artifact (D31) removes content and keeps metadata and lineage marked Deleted so that references stay explainable.

States (ArtifactState)

stateDiagram-v2
    Stored --> Validated : ValidationRecorded
    Stored --> Superseded : NewVersionStored
    Validated --> Superseded : NewVersionStored
    Stored --> Deleted : Delete
    Validated --> Deleted : Delete
    Superseded --> Deleted : Delete

Hold "Alt" / "Option" to enable pan & zoom

Entities: LineageEdge · Value objects: —

ContextSnapshot (ContextBuilderService)¶

The immutable record of one assembly for one attempt — plan, candidates considered, items selected with citations and section, dropped items with reasons, compression applied, token budget and final counts (context-snapshot-v1).

Field	Type	Required	Description
`contextSnapshotId`	`guid`	yes
`tenantId`	`string`	yes
`projectId`	`string`	yes
`runId`	`guid`	yes
`attemptId`	`guid`	yes
`planRef`	`string`	yes	Artifact reference of the context plan (sections, budgets, priorities).
`tokenBudget`	`int`	yes
`tokensUsed`	`int`	yes
`status`	`enum:SnapshotStatus`	yes
`indexRevisions`	`list:guid`	yes	Index revisions queried.
`memoryItems`	`list:guid`	yes	Promoted memory items included (BC-13).
`contentRef`	`string`	yes	Artifact reference of the assembled context (content never in the row).
`assembledAt`	`datetime`	yes

Invariants

Every included item cites its source version, chunk or fact id, index revision and trust tier; an item without provenance is never included.
Only items within the attempt's scope and ACL are considered; the snapshot records the scope used.
The snapshot is immutable; a changed plan or budget produces a new snapshot for a new attempt.
Mandatory instructions and the current task are never truncated; optional sections are cut first and the cut is recorded.

Entities: ContextItem · Value objects: —

MemoryItem (MemoryPromotionService)¶

One memory from observation to promotion — class, scope, provenance (run, attempt, artifacts, sources), evidence verdict, confidence, review decision, reinforcement count, decay and expiry.

Field	Type	Required	Description
`memoryId`	`guid`	yes
`tenantId`	`string`	yes
`projectId`	`string`	no
`scope`	`enum:MemoryScope`	yes
`class`	`enum:MemoryClass`	yes
`state`	`enum:MemoryState`	yes
`summaryRef`	`string`	yes	Artifact reference of the memory text (content never in the row).
`originRunId`	`guid`	yes
`originAttemptId`	`guid`	no
`evidenceRefs`	`list:string`	yes	Artifacts, receipts and source citations supporting the memory.
`confidence`	`decimal`	yes
`trustTier`	`string`	yes	AgentObservation until promoted; InferredFact or SourceFact after evidence check.
`reviewApprovalId`	`guid`	no	Approval of class publication (memory promotion is a gated action, D21).
`reinforcements`	`int`	yes
`lastUsedAt`	`datetime`	no
`expiresAt`	`datetime`	no
`promotedAt`	`datetime`	no
`version`	`long`	yes

Invariants

A memory reaches Promoted only through a review decision bound to its exact content hash (approval of class publication); Shared scope additionally requires the tenant's consent record.
Semantic candidates become organizational facts only with an evidence verdict that cites sources; otherwise they stay AgentObservation and are retrievable only as such.
Procedural candidates that are reinforced beyond the threshold are proposed as skill releases (BC-04), not promoted as memory.
Every memory has an expiry; reinforcement extends it, decay archives it; deletion follows the project's data lifecycle (D31).

States (MemoryState)

stateDiagram-v2
    Observed --> Candidate : ObservationAccepted
    Candidate --> Classified : Classify
    Classified --> Deleted : ClassDiscardOrTemporaryExpired
    Classified --> EvidenceChecked : EvidenceCheck
    EvidenceChecked --> InReview : PolicyRequiresReview
    EvidenceChecked --> Promoted : PolicyAutoPromote
    InReview --> Promoted : ReviewApproved
    InReview --> Archived : ReviewRejected
    Promoted --> Reinforced : UsedSuccessfully
    Reinforced --> Promoted : ReinforcementRecorded
    Promoted --> Decayed : UnusedPastWindow
    Decayed --> Archived : Archive
    Archived --> Deleted : RetentionPassed

Hold "Alt" / "Option" to enable pan & zoom

Entities: ReviewDecision · Value objects: —

KnowledgeSource (KnowledgeIngestionService)¶

A registered source with its connection, extractor, ACL mapping, sync policy and classification; owned by a project or shared at tenant level.

Field	Type	Required	Description
`sourceId`	`guid`	yes
`tenantId`	`string`	yes
`projectId`	`string`	no	Null for a tenant-wide source.
`kind`	`enum:SourceKind`	yes
`reference`	`string`	yes	Repository URL, site, database or API reference.
`connectionId`	`guid`	no	Connection in BC-16 when credentials are needed.
`extractor`	`string`	yes	code
`classification`	`string`	yes	public
`aclMapping`	`json`	yes	How source permissions map to Factory scopes.
`syncPolicy`	`json`	yes	interval, webhook, change detection, re-index triggers
`state`	`enum:SourceState`	yes
`lastSnapshotId`	`guid`	no
`version`	`long`	yes

Invariants

A source belongs to exactly one tenant and is readable only within the project scope that registered it or tenant-wide when declared so.
Credentials are never stored here; a source references a connection (BC-16) and the Secret Broker issues short-lived access.
Deleting a source produces deletion lineage for every derived chunk, vector, graph fact and context snapshot that referenced it (D31).

States (SourceState)

stateDiagram-v2
    Registered --> Syncing : FirstSync
    Syncing --> Healthy : SnapshotPublished
    Healthy --> Syncing : ChangeDetected
    Healthy --> Stale : StalenessWindowExceeded
    Stale --> Syncing : Resync
    Syncing --> Failing : SyncFailed
    Failing --> Syncing : Retry
    Healthy --> Disabled : Disable
    Disabled --> Deleting : Delete
    Healthy --> Deleting : Delete

Hold "Alt" / "Option" to enable pan & zoom

Entities: Collection · Value objects: —

SourceSnapshot (KnowledgeIngestionService)¶

An immutable capture of a source at a version (commit, document revision, export time) that flows through the pipeline; superseded by the next snapshot, never mutated.

Field	Type	Required	Description
`snapshotId`	`guid`	yes
`sourceId`	`guid`	yes
`tenantId`	`string`	yes
`sourceVersion`	`string`	yes	Commit id, revision or export timestamp.
`state`	`enum:SnapshotState`	yes
`documentCount`	`int`	yes
`chunkCount`	`int`	yes
`contentRef`	`string`	yes	Blob prefix of the normalized content.
`takenAt`	`datetime`	yes
`publishedAt`	`datetime`	no

Invariants

A snapshot's documents and chunks are immutable; a change in the source produces a new snapshot and supersedes the old one after publication.
Chunks carry the source version, classification, ACL scope and trust tier SourceFact; indexes are published only after ACL propagation succeeded.

States (SnapshotState)

stateDiagram-v2
    Taken --> Parsed : ParseCompleted
    Parsed --> Chunked : ChunkCompleted
    Chunked --> Indexed : IndexesWritten
    Indexed --> Published : AclPropagated
    Published --> Superseded : NextSnapshotPublished
    Taken --> Failed : StageFailed
    Parsed --> Failed : StageFailed
    Chunked --> Failed : StageFailed

Hold "Alt" / "Option" to enable pan & zoom

Entities: Document, Chunk · Value objects: —

RepositoryIndexSet (RepositoryIntelligenceService)¶

The complete set of indexes of one repository at one revision; immutable once Ready, superseded by the next revision's set.

Field	Type	Required	Description
`indexSetId`	`guid`	yes
`tenantId`	`string`	yes
`sourceId`	`guid`	yes	The GitRepository source in BC-10.
`snapshotId`	`guid`	yes
`revision`	`string`	yes	Commit id.
`state`	`enum:RepoIndexState`	yes
`kinds`	`list:string`	yes	Index kinds built.
`fileCount`	`int`	yes
`symbolCount`	`int`	yes
`languages`	`list:string`	yes
`builtAt`	`datetime`	no

Invariants

Indexes are derived from an immutable snapshot and rebuildable; they never hold content beyond what a tool returns by range.
A tool answer cites the revision; a caller that holds an older revision is told so instead of receiving mixed results.
Write tools (apply patch, create, delete, move, build, test) are not here: they are Tools and MCP tools of their side-effect class acting on a sandboxed workspace (BC-08, BC-26).

States (RepoIndexState)

stateDiagram-v2
    Building --> Ready : BuildCompleted
    Building --> Failed : BuildFailed
    Ready --> Superseded : NextRevisionReady

Hold "Alt" / "Option" to enable pan & zoom

Entities: SymbolEntry, DependencyEdge, OwnershipEntry · Value objects: —

IndexRevision (VectorMemoryService)¶

One revision of one index of a collection, pinned to an embedding profile version and a vector profile; derived, rebuildable state.

Field	Type	Required	Description
`indexRevisionId`	`guid`	yes
`tenantId`	`string`	yes
`collectionId`	`guid`	yes
`kind`	`enum:IndexKind`	yes
`revision`	`int`	yes
`embeddingProfileVersion`	`string`	no	For vector indexes; a profile change means a new revision.
`vectorProfile`	`string`	no	qdrant
`state`	`enum:IndexState`	yes
`itemCount`	`long`	yes
`builtFromSnapshots`	`list:guid`	yes
`builtAt`	`datetime`	no

Invariants

Scope (tenant, project, ACL) is enforced by the backend filter before top-k, never by post-filtering results (ADR-0013).
A revision is immutable once Ready; rebuilding produces the next revision and retires the old one after the switch.
Every retrieved item cites source id, source version, chunk id, embedding profile version and index revision.

States (IndexState)

stateDiagram-v2
    Building --> Ready : BuildCompleted
    Ready --> Rebuilding : RebuildRequested
    Rebuilding --> Ready : BuildCompleted
    Ready --> Degraded : BackendUnhealthy
    Degraded --> Ready : BackendRecovered
    Ready --> Retired : NextRevisionReady

Hold "Alt" / "Option" to enable pan & zoom

GraphFact (VectorMemoryService)¶

A temporal, provenance-carrying relationship in one graph domain (subject, predicate, object, validFrom, validTo, observedAt, sourceVersion, confidence, trust tier).

Field	Type	Required	Description
`factId`	`guid`	yes
`tenantId`	`string`	yes
`domain`	`enum:GraphDomain`	yes
`subject`	`string`	yes
`predicate`	`string`	yes
`object`	`string`	yes
`validFrom`	`datetime`	no
`validTo`	`datetime`	no
`observedAt`	`datetime`	yes
`sourceId`	`guid`	no
`sourceVersion`	`string`	no
`confidence`	`decimal`	yes
`trustTier`	`string`	yes	SourceFact
`verified`	`bool`	yes

Invariants

Historical truth is never replaced by current truth; a changed fact closes validTo and a new fact opens.
Inferred facts and agent observations never outrank source facts in retrieval ranking and are labelled in citations.
A fact without provenance is not stored.

RetrievalQuery (VectorMemoryService)¶

The record of one hybrid retrieval — scope, query hash, filters, indexes used, ranking signals and the cited results; kept for context snapshots and evaluation.

Field	Type	Required	Description
`queryId`	`guid`	yes
`tenantId`	`string`	yes
`projectId`	`string`	yes
`runId`	`guid`	no
`queryHash`	`hash`	yes
`filters`	`json`	yes	metadata, temporal, domain, trust tier
`indexesUsed`	`list:guid`	yes
`resultCount`	`int`	yes
`citationsRef`	`string`	yes	Artifact reference of the cited results.
`latencyMs`	`int`	yes
`executedAt`	`datetime`	yes

Invariants

Results outside the caller's scope are never present in citationsRef; the query records the scope it ran under.