RepositoryIntelligenceService¶

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-39 Repository Intelligence
Platform / plane	Knowledge Platform / Knowledge & Memory
Deployment granularity	module of host · host `KnowledgeHost`
Status	target · `ConnectSoft.Factory.Knowledge.Repositories`
Built from	connectsoft-microservice · libraries: connectsoft-extensions-saas-abstractions, connectsoft-extensions-messaging-model, connectsoft-extensions-persistence-model-nhibernate, connectsoft-extensions-query-model
Decisions	ADR-0013, ADR-0022
Traceability	`FR-05` `FR-07` `FUX-09` `FUX-11` `NFR-07` `NFR-16` `XL-03` `XL-10`

Purpose and responsibilities¶

Large repositories should not be dumped into model context (original handoff §33). RepositoryIntelligenceService builds, for every repository snapshot, the indexes an engineering agent needs to work precisely: file tree, symbol index, type graph, dependency graph, call graph, references, Git history, ownership, build graph and test relationships. It exposes them as the read tools of the original tool list (list_files, search_text, search_symbols, find_references, read_file, read_range, get_dependencies, get_git_diff, git_status) through the Tools & MCP platform. Write tools (apply_patch, create_file, delete_file, move_file, build, test) are not here: they act on a sandboxed workspace and carry their side-effect class (BC-08, BC-26).

BC-39 was added by the design plan to give the §33 indexes and tools an owner distinct from generic ingestion.

Context and boundaries¶

flowchart LR
    S["RepositoryIntelligenceService"]
    ToolAdapterService["ToolAdapterService"] -->|grpc| S
    ContextBuilderService["ContextBuilderService"] -->|grpc| S
    StudioBff["StudioBff"] -->|sync-http| S
    S -->|grpc| KnowledgeIngestionService["KnowledgeIngestionService"]
    S -->|grpc| ArtifactService["ArtifactService"]
    S -. "RepositoryIndexed" .-> E_RepositoryIndexed(("event"))
    S -. "RepositoryIndexFailed" .-> E_RepositoryIndexFailed(("event"))

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

Domain model¶

RepositoryIndexSet — The complete set of indexes of one repository at one revision; immutable once Ready, superseded by the next revision's set. (catalog entry)

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).

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

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

Events: RepositoryIndexed, RepositoryIndexFailed · Tables: RepositoryIndexSets, Symbols, DependencyEdges, Ownership · Repository: RepositoryIndexSetRepository

erDiagram
    RepositoryIndexSet {
        guid indexSetId PK
        string tenantId
        guid sourceId
        guid snapshotId
        string revision
        enum_RepoIndexState state
        list_string kinds
        int fileCount
        int symbolCount
        list_string languages
        datetime builtAt
    }
    SymbolEntry {
        guid symbolId

        string name

        string kind

        string path

        int startLine

        int endLine

        guid containerSymbolId

        hash signatureHash

    }
    DependencyEdge {
        guid edgeId

        string kind

        string fromRef

        string toRef

        string version

    }
    OwnershipEntry {
        string path

        list_string owners

        string lastCommit

        datetime lastChangedAt

        int churn90d

    }
    RepositoryIndexSet ||--o{ SymbolEntry : contains
    RepositoryIndexSet ||--o{ DependencyEdge : contains
    RepositoryIndexSet ||--o{ OwnershipEntry : contains

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

Entities and value objects¶

SymbolEntry (entity, in RepositoryIndexSet) — A symbol with its kind, location and type.

Field	Type	Required	Description
`symbolId`	`guid`	yes
`name`	`string`	yes
`kind`	`string`	yes	namespace
`path`	`string`	yes
`startLine`	`int`	yes
`endLine`	`int`	yes
`containerSymbolId`	`guid`	no
`signatureHash`	`hash`	yes

DependencyEdge (entity, in RepositoryIndexSet) — A project, package, call or reference edge.

Field	Type	Required	Description
`edgeId`	`guid`	yes
`kind`	`string`	yes	project
`fromRef`	`string`	yes
`toRef`	`string`	yes
`version`	`string`	no

OwnershipEntry (entity, in RepositoryIndexSet) — Ownership and history facts per path.

Field	Type	Required
`path`	`string`	yes
`owners`	`list:string`	yes
`lastCommit`	`string`	yes
`lastChangedAt`	`datetime`	yes
`churn90d`	`int`	yes

Data model and storage¶

Store	Role	Engine / profile	Tables
Knowledge metadata store	primary	azure-sql / nhibernate-sqlserver	RepositoryIndexSets, Symbols, DependencyEdges, Ownership
Artifact content store	blob	blob / azure-blob	—

Table	Owner	Columns	Indexes
`dbo.RepositoryIndexSets`	RepositoryIndexSet	11	1
`dbo.Symbols`	SymbolEntry	10	2
`dbo.DependencyEdges`	DependencyEdge	7	2
`dbo.Ownership`	OwnershipEntry	7	0

Full DDL: appendix.

APIs¶

Method	Path	Operation	Scope	Side effects	Idempotency	Gateway	Summary
`GET`	`/factory/repositories/{sourceId}/indexes`	ListRepositoryIndexSets	`factory.knowledge.read`	read	natural	GW-03	Index sets per revision with state and counts.
`POST`	`/factory/repositories/{sourceId}/indexes/rebuild`	RebuildRepositoryIndexes	`factory.knowledge.admin`	shared-write	key-header	GW-03	Rebuild the index set of the latest snapshot.

gRPC service	Method	Streaming	Visibility	Side effects	Summary
`RepositoryIntelligence`	`ListFiles`	none	internal	read	Tool list_files: file tree at a revision with filters.
`RepositoryIntelligence`	`SearchText`	none	internal	read	Tool search_text: full-text search within a repository revision with ranges.
`RepositoryIntelligence`	`SearchSymbols`	none	internal	read	Tool search_symbols: symbols by name, kind and container.
`RepositoryIntelligence`	`FindReferences`	none	internal	read	Tool find_references: references and callers of a symbol.
`RepositoryIntelligence`	`ReadRange`	none	internal	read	Tools read_file and read_range: content by path and line range from the snapshot, never whole repositories.
`RepositoryIntelligence`	`GetDependencies`	none	internal	read	Tool get_dependencies: project, package, call and test-coverage edges of a path or symbol.
`RepositoryIntelligence`	`GetHistory`	none	internal	read	Tools get_git_diff, git_status (read side) and ownership: history, churn and owners of a path.

Every tool answer cites the revision it was computed from; a caller holding an older revision receives a mismatch flag instead of mixed results, and read_range never returns more than the configured line limit.

Messages¶

Event	Topic	Scope / v	Aggregate	Consumers	Summary
RepositoryIndexed	`repo-intelligence.indexes.v1.repository-indexed`	integration / 1	RepositoryIndexSet	ContextBuilderService, VectorMemoryService, StudioBff, DashboardService	An index set is Ready for a revision.
RepositoryIndexFailed	`repo-intelligence.indexes.v1.repository-index-failed`	integration / 1	RepositoryIndexSet	StudioBff, DashboardService	Index build failed; the previous set stays Ready.

RepositoryIndexed payload:

Field	Type	Required
`indexSetId`	`guid`	yes
`tenantId`	`string`	yes
`sourceId`	`guid`	yes
`revision`	`string`	yes
`fileCount`	`int`	yes
`symbolCount`	`int`	yes

RepositoryIndexFailed payload:

Field	Type	Required
`indexSetId`	`guid`	yes
`tenantId`	`string`	yes
`sourceId`	`guid`	yes
`revision`	`string`	yes
`reason`	`string`	yes

Command	Handled by	Result events	Summary
`RebuildRepositoryIndexes`	RepositoryIndexSet	RepositoryIndexed, RepositoryIndexFailed

Event	Producer	Handler	Purpose
SourceSnapshotTaken	KnowledgeIngestionService	`BuildIndexSet`	Build indexes for GitRepository snapshots.
SourceRegistered	KnowledgeIngestionService	`PrepareRepository`	Prepare language analyzers for new repository sources.
SourceDeleted	KnowledgeIngestionService	`RemoveIndexSets`	Remove index sets of a deleted repository source.

Workers and jobs¶

Worker	Trigger	Output events	Retry	Idempotency key	Summary
IndexSetBuilder	event	RepositoryIndexed, RepositoryIndexFailed	exponential	`sourceId + revision + analyzerVersion`	Builds file tree, symbols, types, dependencies, calls, references, history, ownership, build and test relations for a snapshot using language analyzers (Roslyn for .NET first).

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:Repositories`	`Analyzers`	string[]	`[dotnet-roslyn, typescript, generic-text]`	no	no	Language analyzers enabled.
`Knowledge:Repositories`	`MaxRangeLines`	int	`400`	yes	no	Maximum lines a read_range answer returns.
`Knowledge:Repositories`	`KeepRevisions`	int	`3`	yes	no	Index sets kept per repository besides the latest.

Metrics and observability¶

Metric	Instrument	Unit	Dimensions	Summary
`connectsoft.factory.repo_intelligence.index_builds`	counter	{build}	tenant, outcome	Index builds and outcomes.
`connectsoft.factory.repo_intelligence.build_duration`	histogram	s	analyzer	Build duration per analyzer.
`connectsoft.factory.repo_intelligence.tool_calls`	counter	{call}	tenant, tool	Read tool calls.

Security¶


Authentication	client-credentials
Scopes	`factory.knowledge.read` (Read index sets and use read tools in scope.); `factory.knowledge.admin` (Rebuild.)
Roles	Requester, Reviewer, AssetMaintainer, Operator, WorkspaceAdmin, PlatformAdmin, Observer
Tenant isolation	row-filter
Data classification	confidential
Max side-effect class	shared-write
Secrets	—

Dependencies¶

Outbound

Target	Kind	Purpose	Failure mode	Required
KnowledgeIngestionService	grpc	Snapshot content and source scope.	fail-fast	yes
ArtifactService	grpc	Snapshot content by hash.	fail-fast	yes

Inbound

Target	Kind	Purpose	Failure mode	Required
ToolAdapterService	grpc	Repository read tools exposed as MCP tools.	—	yes
ContextBuilderService	grpc	Repository state for context assembly.	—	yes
StudioBff	sync-http	Index views.	—	yes

Failure and recovery¶

Scenario	Detection	Recovery	Data impact	RTO (min)
Analyzer fails on a language or project	build failure	set Failed with reason; previous set serves; generic-text analyzer covers search_text	none	0
Caller holds an older revision	revision mismatch in the request	answer carries the current revision and a mismatch flag; no mixed results	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	—

In the hybrid profile this module runs next to the repositories inside the customer's network.

Current implementation¶

Nothing exists; the earlier AgentKit repository tooling is a reference input only (D19). Roslyn-based analysis is the first analyzer the design assumes for .NET repositories.

Later capabilities¶

Semantic embeddings of symbols for cross-repository search; change-impact analysis across the dependency graph (from the former roadmap); test-selection hints from test relationships; analyzers for further languages.

Decisions and traceability¶

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

Tools & MCP · KnowledgeIngestionService · ContextBuilderService
Knowledge Platform microservices · bounded contexts · APIs · events · data model
Services catalog · Ownership map

RepositoryIntelligenceService¶

Purpose and responsibilities¶

Context and boundaries¶

Domain model¶

Entities and value objects¶

Data model and storage¶

APIs¶

Messages¶

Workers and jobs¶

Actors and grains¶

Sagas and long-running flows¶

Options and configuration¶

Metrics and observability¶

Security¶

Dependencies¶

Failure and recovery¶

NFR targets¶

Deployment¶

Current implementation¶

Later capabilities¶

Decisions and traceability¶

Related¶