ContextBuilderService

Target

This page describes intended behaviour or structure. No implementation is claimed unless a section is explicitly marked Current implementation or Evidence.

Bounded context	BC-09 Context Assembly
Platform / plane	Knowledge Platform / Knowledge & Memory
Deployment granularity	module of host · host KnowledgeHost
Status	target · ConnectSoft.Factory.Knowledge.Context
Built from	connectsoft-microservice · libraries: connectsoft-extensions-ai, connectsoft-extensions-saas-abstractions, connectsoft-extensions-messaging-model, connectsoft-extensions-persistence-model-nhibernate, connectsoft-extensions-compliance
Decisions	ADR-0013, ADR-0014, ADR-0019
Traceability	FR-07 FUX-06 FUX-09 NFR-03 NFR-07 NFR-11 NFR-16 XL-03 XL-07

Purpose and responsibilities

The platform should not simply fill the model's context window (original handoff §19). ContextBuilderService plans per attempt which sections a task needs (mandatory instructions, current task, conversation state, repository state, relevant knowledge, graph neighbours, episodic memory, current diff, tool results, supporting context), retrieves candidates from retrieval, repository intelligence and promoted memory, ranks and deduplicates them, compresses optional sections through a model profile, budgets tokens well below the profile's declared window, assembles the context and records a context snapshot: every included and dropped item with its score, section, citation and reason (FUX-06).

Context and boundaries

flowchart LR
    S["ContextBuilderService"]
    AgentRuntimeService["AgentRuntimeService"] -->|grpc| S
    StudioBff["StudioBff"] -->|sync-http| S
    S -->|grpc| VectorMemoryService["VectorMemoryService"]
    S -->|grpc| MemoryPromotionService["MemoryPromotionService"]
    S -->|grpc| RepositoryIntelligenceService["RepositoryIntelligenceService"]
    S -->|grpc| ModelRouterService["ModelRouterService"]
    S -->|grpc| ArtifactService["ArtifactService"]
    S -->|grpc| PolicyEngineService["PolicyEngineService"]
    S -. "ContextAssembled" .-> E_ContextAssembled(("event"))

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

flowchart LR
    T["Task and attempt scope"] --> P["Context planner<br/>sections and budgets"]
    P --> R["Retrieve candidates<br/>VectorMemoryService"]
    R --> G["Graph expansion"]
    G --> M["Memory retrieval<br/>MemoryPromotionService"]
    M --> RS["Repository state<br/>RepositoryIntelligenceService"]
    RS --> Rk["Ranking"]
    Rk --> D["Deduplication"]
    D --> C["Compression<br/>code-fast profile"]
    C --> B["Token budgeting"]
    B --> A["Assembly"]
    A --> S["Context snapshot<br/>what was used and why"]

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

Domain model

ContextSnapshot — 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). (catalog entry)

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.

Events: ContextAssembled · Tables: ContextSnapshots, ContextItems · Repository: ContextSnapshotRepository

erDiagram
    ContextSnapshot {
        guid contextSnapshotId PK
        string tenantId
        string projectId
        guid runId
        guid attemptId
        string planRef
        int tokenBudget
        int tokensUsed
        enum_SnapshotStatus status
        list_guid indexRevisions
        list_guid memoryItems
        string contentRef
        datetime assembledAt
    }
    ContextItem {
        guid itemId

        enum_ContextSection section

        string sourceKind

        string reference

        string sourceVersion

        string trustTier

        decimal score

        bool included

        string dropReason

        int tokens

        bool compressed

    }
    ContextSnapshot ||--o{ ContextItem : contains

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

Entities and value objects

ContextItem (entity, in ContextSnapshot) — One included or dropped candidate.

Field	Type	Required	Description
itemId	guid	yes
section	enum:ContextSection	yes
sourceKind	string	yes	chunk
reference	string	yes	chunk id, fact id, memory id, artifact id
sourceVersion	string	no
trustTier	string	yes
score	decimal	yes
included	bool	yes
dropReason	string	no
tokens	int	yes
compressed	bool	yes

Data model and storage

Store	Role	Engine / profile	Tables
Knowledge metadata store	primary	azure-sql / nhibernate-sqlserver	ContextSnapshots, ContextItems
Artifact content store	blob	blob / azure-blob	—
Cache and coordination	cache	redis / azure-cache	—

Table	Owner	Columns	Indexes
dbo.ContextSnapshots	ContextSnapshot	13	1
dbo.ContextItems	ContextItem	13	1

Full DDL: appendix.

APIs

Method	Path	Operation	Scope	Side effects	Idempotency	Gateway	Summary
GET	/factory/runs/{runId}/context-snapshots	ListContextSnapshots	factory.runs.read	read	natural	GW-03	Context snapshots of a run with status, budget and counts.
GET	/factory/context-snapshots/{contextSnapshotId}	GetContextSnapshot	factory.runs.read	read	natural	GW-03	Why each item was selected or dropped: sections, scores, citations, compression and budget (FUX-06).

gRPC service	Method	Streaming	Visibility	Side effects	Summary
ContextAssembly	Assemble	none	internal	read	Build the context for an attempt within its token budget and scope; returns the snapshot id and the content reference (context-snapshot-v1).

Messages

Event	Topic	Scope / v	Aggregate	Consumers	Summary
ContextAssembled	context-assembly.snapshots.v1.context-assembled	integration / 1	ContextSnapshot	StudioBff, DashboardService, QualityScoreService	A context snapshot was recorded for an attempt.

ContextAssembled payload:

Field	Type	Required	Description
contextSnapshotId	guid	yes
tenantId	string	yes
runId	guid	yes
attemptId	guid	yes
status	enum:SnapshotStatus	yes
tokensUsed	int	yes
tokenBudget	int	yes

Command	Handled by	Result events	Summary
Assemble	ContextSnapshot	ContextAssembled

Event	Producer	Handler	Purpose
IndexRevisionReady	VectorMemoryService	RefreshIndexCatalog	Know which index revisions are current for planning.
IndexDegraded	VectorMemoryService	MarkDegraded	Plan around a degraded index and mark snapshots Degraded.
GraphFactsUpdated	VectorMemoryService	InvalidateGraphCache	Invalidate cached neighbourhoods.
SourceDeleted	KnowledgeIngestionService	RecordDeletionLineage	Record that snapshots referencing the source carry deleted citations (D31).

Workers and jobs

None modelled

No workers are modelled for this item yet.

Actors and grains

None modelled

No grains are modelled for this item yet.

Sagas and long-running flows

None modelled

No sagas are modelled for this item yet.

Options and configuration

Section	Key	Type	Default	Reloadable	Secret	Summary
Knowledge:Context	DefaultBudgetTokens	int	24000	yes	no	Default budget when the profile and attempt do not set one; always below the profile's reliable context.
Knowledge:Context	SectionBudgets	json	{ MandatoryInstructions: 0.1, CurrentTask: 0.1, ConversationState: 0.1, RepositoryState: 0.2, RelevantKnowledge: 0.25, GraphNeighbours: 0.1, EpisodicMemory: 0.05, CurrentDiff: 0.05, ToolResults: 0.05 }	yes	no	Share of the budget per section before compression.
Knowledge:Context	CompressionProfile	string	code-fast	yes	no	Model profile used for summarising optional sections.

Metrics and observability

Metric	Instrument	Unit	Dimensions	Summary
connectsoft.factory.context.assemblies	counter	{snapshot}	tenant, status	Assemblies by status.
connectsoft.factory.context.tokens_used	histogram	{token}	tenant, section	Tokens per section.
connectsoft.factory.context.assembly_latency	histogram	s	tenant	Time to assemble.
connectsoft.factory.context.dropped_items	counter	{item}	tenant, reason	Candidates dropped by reason.

Security

Authentication	client-credentials
Scopes	factory.runs.read (Read snapshots of runs in scope.)
Roles	Requester, Reviewer, Operator, WorkspaceAdmin, PlatformAdmin, Observer
Tenant isolation	row-filter
Data classification	confidential
Max side-effect class	read
Secrets	—

Only items within the attempt's scope and ACL are ever candidates; classification and redaction decisions from the policy engine apply to every included item; the assembled content is an artifact under the tenant's retention and never a row.

Dependencies

Outbound

Target	Kind	Purpose	Failure mode	Required
VectorMemoryService	grpc	Retrieve and ExpandGraph.	degrade	yes
MemoryPromotionService	grpc	Promoted memory items in scope.	degrade	no
RepositoryIntelligenceService	grpc	Repository state (tree, symbols, dependencies) for the RepositoryState section.	degrade	no
ModelRouterService	grpc	Compression summaries through the compression profile.	degrade	no
ArtifactService	grpc	Store the plan and the assembled content by hash.	fail-fast	yes
PolicyEngineService	grpc	Classification and redaction decisions on included content.	fail-fast	yes

Inbound

Target	Kind	Purpose	Failure mode	Required
AgentRuntimeService	grpc	Assemble per attempt.	—	yes
StudioBff	sync-http	Snapshot views (why each item was selected).	—	yes

Failure and recovery

Scenario	Detection	Recovery	Data impact	RTO (min)
Retrieval degraded	IndexDegraded or Retrieve errors	assemble from remaining sources and mark the snapshot Degraded; the attempt proceeds with reduced recall and the Studio shows it	none	0
Budget cannot hold mandatory sections	mandatory tokens exceed budget	Failed with reason; the attempt fails with class validation instead of silently truncating instructions	none	0
Compression model unavailable	compression call fails	optional sections truncated instead of summarised; recorded as Truncated	none	0

NFR targets

Target	Class value (pilot-interactive)	Override
latency_p95_ms	2000	—
availability_pct	99.5	—
throughput_rps	50	—
rpo_minutes	15	—
rto_minutes	240	—
cost_class	low	—

Deployment

Granularity	module of host · host KnowledgeHost
Topologies	saas-default, hybrid, on-prem, hybrid-compute
Runtime	—; replicas —–—
Ports	—

Current implementation

No context planner, budget, compression or snapshot exists; the agents framework's RAG passes top-k chunks into the prompt. The context builder design page describes the pipeline this service realises.

Later capabilities

"Explain why each source was selected" as a Studio view over the snapshot; reuse suggestions for new project intents; tiered summaries of knowledge clusters; conversation-state summarisation for multi-turn runs.

Decisions and traceability

Family	Ids
FR	FR-07
FUX	FUX-06, FUX-09
NFR	NFR-03, NFR-07, NFR-11, NFR-16
XL	XL-03, XL-07

Related

• Context builder · VectorMemoryService · MemoryPromotionService · AgentRuntimeService

• Knowledge Platform microservices · bounded contexts · APIs · events · data model

• Services catalog · Ownership map