Skip to content

AIFACTORY-FEAT-020: RepositoryIntelligenceService: thin delivery for the first outcome

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.

A design artefact, not a tracker

This backlog is generated from model/backlog/ and validated against the architecture model. No work item exists in any tracker, and no item carries a date, an estimate or an assignee (ADR-0029).

Epic Knowledge Platform (PF-04) · Increment I1 Generate a microservice · State elaborated · Route backend-developer · Build order 64 of 185 (Factory code)

RepositoryIntelligenceService is the service of bounded context BC-39 (Repository Intelligence). Repository indexes per revision — file tree, symbols, types, dependencies, calls, references, Git history, ownership, build and test relationships — built from repository snapshots and exposed as read tools so that large repositories are never dumped into model context (BC-39, original design §33). In this increment it is delivered thin: The seven read tools run inside the sandbox of the tool executor, where the workspace of the run is mounted, and work over that workspace only (D125); no repository index, and no deployed service reads a workspace before the complete delivery. Its own repository is ConnectSoft.AI.SoftwareFactory.RepositoryIntelligenceService.

Delivers RepositoryIntelligenceService (thin): The seven read tools run inside the sandbox of the tool executor, where the workspace of the run is mounted, and work over that workspace only (D125); no repository index, and no deployed service reads a workspace before the complete delivery.
Stubs —
Realizes adrs: ADR-0013, ADR-0022
Requirements FR-05, FR-07, FUX-09, FUX-11, NFR-07, NFR-16, XL-03, XL-10
Depends on —
Sources model/services/knowledge/RepositoryIntelligenceService.yaml

Scenarios to trace (11, catalog): SCN-RepositoryIntelligenceService-001, SCN-RepositoryIntelligenceService-002, SCN-RepositoryIntelligenceService-003 ✓, SCN-RepositoryIntelligenceService-004 ✓, SCN-RepositoryIntelligenceService-005 ✓, SCN-RepositoryIntelligenceService-006 ✓, SCN-RepositoryIntelligenceService-007 ✓, SCN-RepositoryIntelligenceService-008 ✓, SCN-RepositoryIntelligenceService-009 ✓, SCN-RepositoryIntelligenceService-010, SCN-RepositoryIntelligenceService-011

AIFACTORY-US-062: RepositoryIntelligenceService answers the chain with its thin contract

behavior · persona requester As a requester, I want RepositoryIntelligenceService to answer the read tools of my run from the workspace of that run, so that the agents of the chain read what earlier steps wrote without a repository ever being dumped into model context.

This is the integration PBI of the thin delivery. RepositoryIntelligenceService is the service of bounded context BC-39. In its complete form it builds one index set per repository revision from snapshots and answers read tools from those indexes; that form arrives with feature repository-intelligence-service-complete in I5. The first outcome needs less: the nine agents of the chain read the files that the steps of their own run wrote. The thin scope is exactly this (D125): the seven read tools run inside the sandbox of the tool executor, where the workspace of the run is mounted read-only, and work over that workspace only; no repository index exists, and no deployed service reads a workspace from outside a sandbox before the complete delivery in I5. The seven tools are the seven internal gRPC methods of the service RepositoryIntelligence: ListFiles for list-files, SearchText for search-text, SearchSymbols for search-symbols, FindReferences for find-references, ReadRange for read-range, GetDependencies for get-dependencies and GetHistory for get-git-diff. In this increment the handlers of these seven methods are not reached by a call to a deployed service. The repository packages them as a tool component, and ToolExecutorHost runs that component inside the sandbox of the run, where the sandbox lease mounts the workspace of the run read-only; the component answers the same seven methods with the same request and reply messages and the same golden argument shapes that the complete delivery answers from its indexes in I5 (D125). Every tool call still passes ToolAdapterService, the governed executor (ADR-0022 decision 2): its pipeline authorizes the call, leases the sandbox and executes the tool there, and the method of the tool receives the invocation of tool-invocation-v1 and the workspaceRef of the run, which the lease hands over (feature tool-adapter-service). Whether a call needs an approval is decided by the policy decision of that pipeline alone, for every side-effect class; the component evaluates no policy and no approval and writes no audit evidence, because audit is the last stage of that pipeline. The hosting of the component is a dependency in words on feature tool-executor-host: how ToolExecutorHost takes the component, starts it in the sandbox of a run and hands it the mounted workspace with the reference and the scope of the lease is delivered by the PBIs of that feature, which are aligned with this decision in their own pass, and this feature delivers the component and its contract. What holds inside the sandbox replaces what a deployed service would check. The component validates no token and holds no credential, because no caller reaches it over the network of the cluster: its only caller is the host that ToolExecutorHost runs in the same sandbox, for a call the pipeline authorized. The tenant, the project and the run of a call are those of the scope and the runId of the invocation, and the boundary is the sandbox itself: one workspace is mounted, it is mounted read-only, and the lease names the tenant, the project and the run it belongs to. The service scope of a workload token, by which the deployed service of I5 admits its internal gRPC methods, and the scope factory.knowledge.read, which guards the public REST operations that read index sets, are stated by the model for that delivery (D125) and are checked by nothing inside the sandbox. The workspace of a run is owned by ExecutionCapacityService, which creates it with the first lease of the run, keeps it between leases and removes it on a terminal run event. The handlers read it through one port, the workspace view (AIFACTORY-US-816), whose production binding is the mounted workspace of the sandbox. The feature is delivered by four further PBIs: the workspace view port with its boundary rules (AIFACTORY-US-816), the three file tools (AIFACTORY-US-817), the three analysis tools (AIFACTORY-US-818) and the diff and status of the workspace (AIFACTORY-US-819). Nothing else is served. The REST operations ListRepositoryIndexSets and RebuildRepositoryIndexes, the aggregate RepositoryIndexSet with its three transitions, the events RepositoryIndexed and RepositoryIndexFailed, the worker IndexSetBuilder and the nine consumed events arrive with the complete delivery; the handler of DeletionOrderIssued is built in I4 with RetentionResidencyService and is not registered here. The thin delivery delivers no aggregate, so no state transition exists to cover; it writes no row to repository-intelligence-sql and no outbox record, and it calls neither KnowledgeIngestionService nor ArtifactService, the two outbound dependencies of the model, because both serve snapshots and the thin delivery reads none. The repository ConnectSoft.AI.SoftwareFactory.RepositoryIntelligenceService is created and scaffolded in I0 by AIFACTORY-TASK-067 of feature repository-and-pipeline-conventions (D140), and this feature starts from that scaffold, and is scaffolded once from the pinned base template package with UseFactoryProfile (features component-base-template-factory-profile and component-base-template-findings). The scaffold brings the service host with token validation, the scope chain with its 401, 403 and 404 answers, health, readiness, the messaging profile repository-intelligence with its outbox and inbox and the telemetry wiring; the complete delivery builds on that host in I5, and the thin delivery deploys no instance of it. What the thin delivery adds to the repository is the tool component: the seven handlers, the workspace view with its mounted-workspace binding, the analyzers and the gRPC surface of RepositoryIntelligence, which the pipeline of the repository publishes as a package beside the container image of the service. The component references neither repository-intelligence-sql nor the messaging profile, holds no secret and opens no network connection, so it runs in a sandbox whose network is closed. The form in which ToolExecutorHost takes a tool component is defined by feature tool-executor-host and is reported with that dependency. The model names tool-invocation-v1 as the request and as the reply descriptor of all seven methods. docs/reference/schemas/tool-invocation.schema.json describes the governed request and its receipt and has no shape for the result of a read tool. That gap is reported to the owner, and the thin delivery makes its contract checkable without deciding it: the proto fixes one request message for all seven methods, which carries the invocation and the workspaceRef, and one typed reply message per method, and the complete delivery answers the same messages from its indexes. The arguments of a tool live in one place, the arguments member of the invocation, and in no typed request member beside it. The contract test fixes one argument shape per tool: a path prefix, a name pattern and a depth for ListFiles, the text and an optional path prefix for SearchText, a name, a kind and a container for SearchSymbols, a symbol for FindReferences, a path and a line range for ReadRange, a path or a symbol for GetDependencies and optional paths for GetHistory, each with the continuation token of a paged answer; arguments that do not match the shape of the tool are refused with INVALID_ARGUMENT. The schema of the invocation also holds an optional sandbox.workspaceId. The component resolves the workspace from the workspaceRef member of the request only and never from the invocation; a request whose invocation carries a sandbox.workspaceId that differs from the workspaceRef is refused with INVALID_ARGUMENT before anything is read, so two carriers can never point a tool at two workspaces. Whether the two members name the same identifier is reported with the same gap. A reply cites the workspaceRef it was read from; its revision member stays empty, because a workspace is the working state of a run and no snapshot at a commit, and what a workspace answer cites in the place of the revision the model requires is reported with the same gap. Every call is counted in connectsoft.factory.repo_intelligence.tool_calls through the helper of the pinned observability library, which puts the tenant and the project on the instrument beside the tool; no file content, no query text and no path listing reaches a log record, an activity or a metric (ADR-0019). How the telemetry of a component leaves the sandbox is the matter of its host and belongs to the dependency on feature tool-executor-host.

Acceptance criteria

AC1 Given the repository ConnectSoft.AI.SoftwareFactory.RepositoryIntelligenceService created and scaffolded in I0 by AIFACTORY-TASK-067 of feature repository-and-pipeline-conventions, whose first commit is the unchanged output of dotnet new connectsoft-base -n ConnectSoft.AI.SoftwareFactory.RepositoryIntelligenceService --UseFactoryProfile true from the pinned template package, when its pipeline runs with the work of this feature, then no second scaffold was run, the solution builds, the unit and acceptance tests pass with complete reports and a container image is published (ADR-0028, model/services/knowledge/RepositoryIntelligenceService.yaml).
AC2 Given the tool component of the repository hosted over a sandbox fixture whose workspace is mounted read-only, when RepositoryIntelligenceService/RepositoryIntelligence.ListFiles, RepositoryIntelligenceService/RepositoryIntelligence.SearchText, RepositoryIntelligenceService/RepositoryIntelligence.SearchSymbols, RepositoryIntelligenceService/RepositoryIntelligence.FindReferences, RepositoryIntelligenceService/RepositoryIntelligence.ReadRange, RepositoryIntelligenceService/RepositoryIntelligence.GetDependencies and RepositoryIntelligenceService/RepositoryIntelligence.GetHistory are called with the workspaceRef of the run of that sandbox and the arguments of their tool in the arguments member of the invocation, then all seven answer from that mounted workspace only, each with the reply message the contract test fixes and the workspaceRef it read, with the same request and reply messages and the same seven golden argument shapes that the service descriptor of the repository lists for the deployed service of I5, and a request whose invocation carries a sandbox.workspaceId that differs from the workspaceRef is refused with INVALID_ARGUMENT, as AIFACTORY-US-817 to AIFACTORY-US-819 prove one by one (ADR-0022, FR-05).
AC3 Given the service descriptor of the thin delivery and the packaged tool component, when the contract test compares the surface of the component with the descriptor, then exactly the seven methods of RepositoryIntelligence are answered by the component, it hosts no REST operation, references no store, no messaging profile and no secret, the OrleansMessaging section of the repository declares no published and no consumed event, no row of an index set is written to repository-intelligence-sql, and the test fails when an operation outside the thin scope stated in model/backlog/features/knowledge.yaml appears.
AC4 Given the component in a sandbox fixture whose workspace is mounted read-only and whose network is closed, when the seven methods are called, then every answer is read from the mounted workspace alone, no call validates a token, uses a credential or opens a network connection, a write to the mount fails, and an invocation whose workspaceRef, tenant, project or run is not the one of the lease that mounted the workspace is answered NOT_FOUND before anything is read; no deployed service is called in any of these cases, as the invariants of model/services/knowledge/RepositoryIntelligenceService.yaml state for I1 (ADR-0015, ADR-0022).
AC5 Given calls of two tenants and two projects through the seven methods, each in the sandbox fixture of its run, when the metrics, the logs and the activities of the component are read, then connectsoft.factory.repo_intelligence.tool_calls counts every call with its tenant, its project and its tool, and no record holds file content, query text or a path listing (ADR-0019, model/services/knowledge/RepositoryIntelligenceService.yaml).
Traces: services RepositoryIntelligenceService, ToolExecutorHost
Traces: apis RepositoryIntelligenceService/RepositoryIntelligence.ListFiles, RepositoryIntelligenceService/RepositoryIntelligence.SearchText, RepositoryIntelligenceService/RepositoryIntelligence.SearchSymbols, RepositoryIntelligenceService/RepositoryIntelligence.FindReferences, RepositoryIntelligenceService/RepositoryIntelligence.ReadRange, RepositoryIntelligenceService/RepositoryIntelligence.GetDependencies, RepositoryIntelligenceService/RepositoryIntelligence.GetHistory
Traces: tools list-files, search-text, search-symbols, find-references, read-range, get-dependencies, get-git-diff
Traces: descriptors tool-invocation-v1
Traces: adrs ADR-0013, ADR-0015, ADR-0019, ADR-0022, ADR-0028
Traces: requirements FR-05
Depends on AIFACTORY-US-816, AIFACTORY-US-817, AIFACTORY-US-818, AIFACTORY-US-819, feature:repository-and-pipeline-conventions, feature:component-base-template-factory-profile, feature:component-base-template-findings, feature:component-observability-factory-conventions, feature:contracts-package
Sources model/services/knowledge/RepositoryIntelligenceService.yaml, model/backlog/features/knowledge.yaml, docs/reference/schemas/tool-invocation.schema.json, docs/architecture/adr/0022-mcp-as-tool-protocol.md, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, docs/planes/knowledge-memory/services/repository-intelligence-service/index.md#purpose-and-responsibilities

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-069 Contract of the thin surface: service descriptor and proto of the seven tool methods with the invocation, the argument shape of each tool and the workspace reference contract The service descriptor file of the repository lists exactly the seven methods of RepositoryIntelligence, all internal, unary and of class read. The proto fixes one request message for all seven methods, which carries the invocation of tool-invocation-v1 and the workspaceRef of the run, and one typed reply message per method: file entries with path, kind (file, directory or link) and length for ListFiles, matches with path and line range for SearchText, symbol entries for SearchSymbols, reference locations for FindReferences, lines with the returned range for ReadRange, edges for GetDependencies and status entries with diff hunks for GetHistory; every reply carries the workspaceRef it was read from, a revision member that stays empty in the thin delivery, a partial mark with the names of what was not analysed where the method analyses, and a continuation token where the answer is paged. The arguments of a tool live in the arguments member of the invocation and in no typed request member beside it. The contract holds seven golden argument shapes, one per tool: a path prefix, a name pattern and a depth for ListFiles; the text and an optional path prefix for SearchText; a name, a kind and a container for SearchSymbols; a symbol for FindReferences; a path and a line range for ReadRange; a path or a symbol for GetDependencies; optional paths for GetHistory; each shape also holds the continuation token of a paged answer, and each method validates the arguments of its request against the shape of its tool and refuses a mismatch with INVALID_ARGUMENT. The component resolves the workspace from the workspaceRef member of the request only; a request whose invocation carries a sandbox.workspaceId that differs from the workspaceRef is refused with INVALID_ARGUMENT, and the contract test holds that case. A contract test with golden files compares the invocation member with docs/reference/schemas/tool-invocation.schema.json and holds the seven argument shapes and the seven reply shapes; it is the same set of shapes that the contract test of AIFACTORY-TASK-220 of feature tool-adapter-service holds against the calls of the executor. The contract test compares the surface of the tool component with the service descriptor file in both directions, so the component that ToolExecutorHost runs in the sandbox of the run in I1 and the deployed service of the complete delivery in I5 answer the same seven methods with the same messages and the same golden argument shapes, without a contract change (D125). ConnectSoft.AI.SoftwareFactory.RepositoryIntelligenceService
AIFACTORY-TASK-3291 Packaging of the read-tool component: the package of the seven handlers, its options and the tool call metric operations The pipeline of the repository publishes the tool component as a package beside the container image of the service: the seven handlers of RepositoryIntelligence, the workspace view port with its mounted-workspace binding, the analyzers and the gRPC surface of the seven methods; the component reads the options Knowledge:Repositories:Analyzers and Knowledge:Repositories:MaxRangeLines at their modelled defaults from the configuration its host passes, references no store, no messaging profile and no secret, binds no base address of KnowledgeIngestionService or ArtifactService, which the thin delivery does not call, and opens no network connection; connectsoft.factory.repo_intelligence.tool_calls is registered through the helper of the pinned observability library with tenant, project and tool; no instance of the service is deployed in I1, so the deployment manifest with the replica range 2 to 10 of model/services/knowledge/RepositoryIntelligenceService.yaml, the probes and the secret reference messaging-transport arrives with the complete delivery in I5 (D125); the hosting of the component in the sandbox of a run belongs to feature tool-executor-host. ConnectSoft.AI.SoftwareFactory.RepositoryIntelligenceService
AIFACTORY-TASK-764 Verify repository-intelligence-service-thin-contract by running the declared command verification Run dotnet build -c Release and dotnet test -c Release --no-build in the pipeline of the repository; a run that discovers no test counts as a failure; the runs pass and prove AC1 to AC5 of AIFACTORY-US-062, that is the scaffold, the seven methods answered by the tool component from the mounted workspace of one sandbox fixture (SCN-RepositoryIntelligenceService-003 to SCN-RepositoryIntelligenceService-009), the surface of the component compared with the service descriptor, with no store, no messaging profile and no secret, the golden files of the invocation member, of the seven argument shapes and of the seven reply shapes, the refused request whose sandbox.workspaceId differs from the workspaceRef, the component in a sandbox fixture with a closed network and a read-only mount that validates no token and opens no connection, the NOT_FOUND for an invocation of another lease and the telemetry conformance test over two tenants and two projects. ConnectSoft.AI.SoftwareFactory.RepositoryIntelligenceService

AIFACTORY-US-816: Workspace view port: one read-only, bounded view of the workspace of a run by its reference, with the path and scope boundary every read tool passes

enabling · persona operator As an operator, I want every read tool to reach a workspace through one port with one boundary, so that a tool can never read another run, another tenant or the host, whatever its arguments say.

A read tool of the thin delivery reads one thing: the workspace of the run that called it. ExecutionCapacityService owns that workspace: it creates it with the first lease of the run, keeps it between leases, hands its reference to ToolAdapterService by lease as workspaceRef and removes it when it consumes a terminal run event (model/services/runtime-cloud/ExecutionCapacityService.yaml). How a read tool reaches it is decided (D125): the sandbox lease mounts the workspace read-only in the sandbox of the run, ToolExecutorHost runs the read-tool component there, and no deployed service reads a workspace from outside a sandbox before the complete delivery in I5. This PBI delivers the port all seven tool methods read through, the rules that bound it and its production binding, the mounted workspace of the sandbox. The binding serves exactly one workspace: the directory the lease mounted, with the workspaceRef, the tenant, the project and the run of that lease, which the host hands to the component with the mount (feature tool-executor-host). The port takes the workspaceRef of the request together with the tenant, the project and the run of the invocation and yields a view of that one workspace: its file tree, the lines of a file by path and range and, where the workspace holds version control metadata, its base, its status and its diff. The view has four rules. It is read-only: the port has no write operation, because write tools act on the sandboxed workspace through ToolAdapterService and are not here (invariant of the model), and the mount is read-only as well, so a defect of a handler cannot change a file. It is bounded by the root: a path is resolved relative to the root of the workspace, and a path that leaves it, by parent segments, as an absolute path or through a symbolic link whose target lies outside, is refused with INVALID_ARGUMENT and nothing is read. A walk of the tree, by the listing, by the text search or by an analysis, returns a symbolic link whose target lies outside the root as an entry of kind link and never follows it, so no path and no match outside the root appears in any reply. It is bound to the scope: a view is yielded only when the workspaceRef, the tenant, the project and the run of the call are those of the lease that mounted the workspace, so a reference of another run, of another project of the same tenant or of another tenant is an unknown reference there, and the method answers NOT_FOUND. That is a rule of this port and no decision of the tenancy record: ADR-0015 amendment D113 decides the answer for a resource of another tenant, which over gRPC is NOT_FOUND, and keeps the refusal for a missing right inside the tenant. The port gives one answer to five cases, a workspace of another tenant, a workspace of another project of the same tenant, a workspace of another run, an unknown reference and a workspace that was removed after its run ended, so the answer never confirms that a workspace exists. Inside the sandbox one answer is also the only possible one, because the component sees one workspace and cannot tell the cases apart; whether a deployed service that reads workspaces by reference answers PERMISSION_DENIED for a workspace of the same tenant is left to the complete delivery in I5. It is bounded in volume: the view returns entries and ranges and never a workspace as one answer, and a file read is capped by Knowledge:Repositories:MaxRangeLines. The production binding reads the mounted directory and nothing else: it calls no operation of ExecutionCapacityService and no other service, needs no credential and no network, and reads the base, the status and the diff from the version control metadata the mounted workspace holds, without writing to it. The acceptance suite runs that binding over sandbox fixtures, directory trees of the test host mounted read-only with the lease values of two runs of one project of one tenant, one run of a second project of that tenant and one run of a second tenant. The proof with a leased sandbox, the component hosted by ToolExecutorHost and a workspace of ExecutionCapacityService belongs to the features tool-executor-host and tool-adapter-service, whose PBIs are aligned with this decision in their own pass. When the mounted workspace cannot be read, the method answers UNAVAILABLE with a reason that names the port and invents no file and no empty listing, and when a read is slower than the deadline of the call, the method ends with DEADLINE_EXCEEDED; in both cases the executor ends the tool call Failed with the failure class transient in its own PBI. The port stores nothing and caches nothing: no workspace content is copied into repository-intelligence-sql or into artifact-blob, no index set is derived from it, and every operation reads the workspace as it is at the moment of the call, so a read made after a write tool of the run changed a file returns the changed content.

Acceptance criteria

AC1 Given the mounted-workspace binding of the port over the sandbox fixture of run A, when a view is opened with the workspaceRef, the tenant, the project and the run of A, then it yields the file tree and the lines of that mounted workspace only, the port exposes no write operation, a write to the mount fails because it is read-only, and nothing is written to repository-intelligence-sql, as the invariants of model/services/knowledge/RepositoryIntelligenceService.yaml require.
AC2 Given a view of the workspace of run A, when a path with parent segments that leave the root, an absolute path or a symbolic link whose target lies outside the root is read, then the read is refused with INVALID_ARGUMENT, no byte outside the root is returned and the host file system is never listed; when the tree, the text search or an analysis walks that workspace, then the link is returned as an entry of kind link, is not followed, and no path or match outside the root appears in any reply (FR-05, ADR-0022).
AC3 Given the fixture with two runs of one project of one tenant, one run of a second project of that tenant and one run of a second tenant, when a view is asked for the workspaceRef of another run, of the other project of the same tenant, of the other tenant, for an unknown reference or for a workspace removed after its run ended, then every one of the five is answered NOT_FOUND with the same reply and nothing is read: for the other tenant as ADR-0015 amendment D113 decides, and for the other four because the binding serves only the one workspace its lease mounted, for the tenant, the project and the run of that lease (ADR-0015, model/services/knowledge/RepositoryIntelligenceService.yaml).
AC4 Given a sandbox fixture whose mounted workspace cannot be read, and one whose reads are slower than the deadline of the call, when any tool method is called, then the answer is UNAVAILABLE with a reason that names the workspace view port in the first case and DEADLINE_EXCEEDED in the second, and no file, listing or empty result is invented; and given the binding over a readable mount, then it called no operation of ExecutionCapacityService or of any other service and opened no network connection, because the mounted workspace of the sandbox is its only source (model/services/knowledge/RepositoryIntelligenceService.yaml, model/services/runtime-cloud/ExecutionCapacityService.yaml).
Traces: services RepositoryIntelligenceService, ExecutionCapacityService, ToolExecutorHost
Traces: adrs ADR-0015, ADR-0022
Traces: requirements FR-05
Depends on feature:component-base-template-factory-profile
Sources model/services/knowledge/RepositoryIntelligenceService.yaml, model/services/runtime-cloud/ExecutionCapacityService.yaml, model/services/tools-mcp/ToolAdapterService.yaml, model/services/tools-mcp/ToolExecutorHost.yaml, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/planes/knowledge-memory/services/repository-intelligence-service/index.md#dependencies

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-3292 Workspace view port with its mounted-workspace binding: read-only operations, root boundary, scope binding and volume bounds contract The application layer holds one port with the operations the seven tool methods need (tree, lines by path and range, base, status and diff) and no write operation; a view is opened with workspaceRef, tenant, project and run; the production binding is the mounted workspace of the sandbox (D125): it serves the one directory the lease mounted read-only, with the workspaceRef, the tenant, the project and the run of that lease as the host of the component hands them over, reads base, status and diff from the version control metadata of that directory without writing to it, calls no service and opens no network connection; a view is yielded only for the workspaceRef, the tenant, the project and the run of that lease, and every other reference, also one of another run, another project or another tenant, is refused with NOT_FOUND with one reply; every path is resolved against the root and a path that leaves it by parent segments, as an absolute path or through a symbolic link is refused with INVALID_ARGUMENT before any read; a walk of the tree returns a symbolic link whose target lies outside the root as an entry of kind link and never follows it; the port holds no cache and no state of a workspace, so every operation reads the workspace as it is at the moment of the call; entries are paged and a file read is capped by Knowledge:Repositories:MaxRangeLines; a mounted workspace that cannot be read surfaces as UNAVAILABLE with the port named. ConnectSoft.AI.SoftwareFactory.RepositoryIntelligenceService
AIFACTORY-TASK-3293 Sandbox fixtures of the workspace view port with four mounted fixture workspaces across two tenants, with two projects in the first tenant fixture The acceptance suite holds sandbox fixtures for the mounted-workspace binding of the port: directory trees of the test host mounted read-only, each with the workspaceRef, the tenant, the project and the run of its lease, for four fixture workspaces: two runs of one project of one tenant, one run of a second project of that tenant and one run of a second tenant; one workspace holds a .NET project, a TypeScript project, plain text files, a file longer than Knowledge:Repositories:MaxRangeLines, a symbolic link that points outside its root and version control metadata with a base and uncommitted changes; a double that wraps the binding can be switched to a mount that cannot be read, to reads slower than the deadline of a call and to a removed workspace, the suite can add and change a file of a fixture workspace between two calls through a second, writable mount of the same tree, as a write tool of the run would, and the test host records every network connection of the component and every file read outside the root. ConnectSoft.AI.SoftwareFactory.RepositoryIntelligenceService
AIFACTORY-TASK-3294 Verify the workspace view port through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&Feature=WorkspaceView"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-816 with the mounted-workspace binding over the sandbox fixtures of AIFACTORY-TASK-3293: the view of one mounted workspace without a write operation, the refused write to the read-only mount, the three refused path forms, the link with a target outside the root returned as an entry of kind link and not followed by the listing, the text search and an analysis, with no path or match outside the root in any reply, the five NOT_FOUND cases with one reply, among them the workspace of the second project of the same tenant, the mount that cannot be read answered UNAVAILABLE, the slow read answered DEADLINE_EXCEEDED, no call to ExecutionCapacityService or another service and no network connection, and an empty repository-intelligence-sql after the run, against model/services/knowledge/RepositoryIntelligenceService.yaml. ConnectSoft.AI.SoftwareFactory.RepositoryIntelligenceService

AIFACTORY-US-817: List the files, search the text and read a line range of the workspace of a run through the three file tools

behavior · persona requester As a requester, I want the agents of my run to list, search and read the files earlier steps of the run wrote, range by range, so that a later step builds on the exact files of the run and never receives a whole repository as context.

An agent of the chain calls list-files, search-text or read-range through ToolAdapterService. The call is executed inside the sandbox of the run, where ToolExecutorHost runs the read-tool component over the workspace mounted read-only (D125), and reaches RepositoryIntelligence.ListFiles, RepositoryIntelligence.SearchText or RepositoryIntelligence.ReadRange of the component with the invocation of tool-invocation-v1 and the workspaceRef of the run. The arguments of each tool are the arguments member of that invocation, in the shape the contract test of AIFACTORY-TASK-069 fixes for the tool, and the request carries no typed argument member beside it. The component validates no token: its only caller is the host in the same sandbox, and the tenant, the project and the run of a call are those of the scope and the runId of the invocation, which must be those of the lease that mounted the workspace (AIFACTORY-US-816). Each method opens the workspace view of the run (AIFACTORY-US-816), whose binding is the mounted workspace, and answers from it alone. ListFiles returns the file tree of the workspace as entries with path, kind (file, directory or link) and length, narrowed by the three filters its arguments carry, a path prefix, a name pattern and a depth, and paged with a continuation token, so a large tree never arrives as one answer. SearchText takes the text and an optional path prefix from its arguments, searches the text files of the workspace through the generic-text analyzer and returns each match as a path with its line range; it returns no file content beyond the matched range, and the caller reads on with ReadRange. ReadRange takes a path and a line range from its arguments and returns the lines of that one file; the tools read_file and read_range of the model are this one method, a file read being a range that starts at line one. An answer returns at most Knowledge:Repositories:MaxRangeLines lines, 400 by default and reloadable; a wider request returns the first lines of the range up to the cap and names the range it returned, so the caller asks for the next range, and no request returns a whole repository (ADR-0013 decision 4 names such bounded reads as an accepted retrieval path). Every reply cites the workspaceRef it was read from and leaves the revision member empty. The three methods are of class read: they write no row, no artifact and no outbox record and publish no event, and a repeated call over an unchanged workspace returns the same answer. The methods keep nothing between calls and the workspace view holds no cache, so a call made after a write tool of the same run added or changed a file returns the new state: the new entry in the listing, the new match in the search and the new lines in the range. The statuses UNAUTHENTICATED and PERMISSION_DENIED belong to the deployed service of the complete delivery, which validates a workload token; the component in the sandbox never answers them. A request without a workspaceRef, without the tenant, the project or the run in the invocation, with arguments that do not match the shape of the tool, with a sandbox.workspaceId in the invocation that differs from the workspaceRef, with a range whose start lies after its end or before line one, or with a path that leaves the workspace is refused with INVALID_ARGUMENT. A workspaceRef, a tenant, a project or a run that is not the one of the lease that mounted the workspace is answered NOT_FOUND. For a workspace of another tenant that is the answer ADR-0015 amendment D113 decides; for a workspace of another run or of another project of the same tenant and for an unknown reference it is the rule of the workspace view (AIFACTORY-US-816), and the reply is the same in every case. A path that does not exist in the workspace is answered NOT_FOUND as well. When the mounted workspace cannot be read, the method answers UNAVAILABLE and returns no partial listing presented as complete. The executor passes the deadline of the tool with the call, 30 seconds for list-files and search-text and 15 seconds for read-range in the catalogue; a call that does not finish within that deadline ends with DEADLINE_EXCEEDED and returns nothing as if complete. ToolAdapterService ends the tool call Failed with the failure class transient in both cases, in its own PBI, and a retry of a read is safe. The call is counted in connectsoft.factory.repo_intelligence.tool_calls with tenant, project and tool, and neither the query of a search nor a line of a file reaches telemetry (ADR-0019).

Acceptance criteria

AC1 Given the tool component over the sandbox fixture of a run, whose workspace is mounted read-only, when RepositoryIntelligenceService/RepositoryIntelligence.ListFiles is called with the workspaceRef of the run, a path prefix and a name pattern, then the reply holds only the entries of that workspace that match, each with path, kind and length, a continuation token when more entries exist, the workspaceRef and an empty revision, and nothing is written (SCN-RepositoryIntelligenceService-003, FR-05).
AC2 Given text that occurs in three files of the workspace, when RepositoryIntelligenceService/RepositoryIntelligence.SearchText is called with that text, then the reply holds one match per occurrence as a path with its line range through the generic-text analyzer, no file content beyond the matched ranges and no match from another workspace, and a second call over the unchanged workspace returns the same matches; given a file with that text added to the workspace and a line of an existing file changed between two calls, when RepositoryIntelligenceService/RepositoryIntelligence.ListFiles, RepositoryIntelligenceService/RepositoryIntelligence.SearchText and RepositoryIntelligenceService/RepositoryIntelligence.ReadRange are called again, then the listing holds the new entry, the search the new match and the range the changed line, and no reply holds the earlier state (SCN-RepositoryIntelligenceService-003, SCN-RepositoryIntelligenceService-004, SCN-RepositoryIntelligenceService-007, XL-03).
AC3 Given a file of the workspace longer than Knowledge:Repositories:MaxRangeLines, when RepositoryIntelligenceService/RepositoryIntelligence.ReadRange is called for lines within the cap, for the whole file and for a range wider than the cap, then the first call returns exactly the lines asked for, and the other two return the first lines up to the cap and name the range returned, so no call returns more than the cap and none returns a repository (SCN-RepositoryIntelligenceService-007, ADR-0013).
AC4 Given a request without a workspaceRef, with arguments that do not match the shape of the tool, with a sandbox.workspaceId that differs from the workspaceRef, with an invalid range or with a path that leaves the workspace, and a workspaceRef of another tenant, of another project or run of the same tenant or a path that does not exist, when any of the three methods is called in the sandbox fixture, then the call is refused with INVALID_ARGUMENT or NOT_FOUND respectively, a workspace of another tenant is answered exactly as an unknown one, no call validated a token, and nothing is read (SCN-RepositoryIntelligenceService-003, SCN-RepositoryIntelligenceService-004, SCN-RepositoryIntelligenceService-007, ADR-0015).
AC5 Given the mounted workspace cannot be read, when any of the three methods is called, then the answer is UNAVAILABLE without a partial result and a repeated call after recovery returns the full answer; given reads of the mounted workspace are slower than the deadline the executor passes, when any of the three methods is called, then the call ends with DEADLINE_EXCEEDED and returns nothing as if complete; in every case connectsoft.factory.repo_intelligence.tool_calls counted the call with tenant, project and tool while no query text and no file line reached a log record, an activity or a metric (SCN-RepositoryIntelligenceService-003, SCN-RepositoryIntelligenceService-004, SCN-RepositoryIntelligenceService-007, ADR-0019, model/services/knowledge/RepositoryIntelligenceService.yaml).
Traces: services RepositoryIntelligenceService, ToolAdapterService
Traces: apis RepositoryIntelligenceService/RepositoryIntelligence.ListFiles, RepositoryIntelligenceService/RepositoryIntelligence.SearchText, RepositoryIntelligenceService/RepositoryIntelligence.ReadRange
Traces: tools list-files, search-text, read-range
Traces: descriptors tool-invocation-v1
Traces: adrs ADR-0013, ADR-0015, ADR-0019, ADR-0022
Traces: requirements FR-05, XL-03
Traces: scenarios SCN-RepositoryIntelligenceService-003, SCN-RepositoryIntelligenceService-004, SCN-RepositoryIntelligenceService-007
Depends on AIFACTORY-US-816, feature:component-base-template-factory-profile, feature:component-observability-factory-conventions
Sources model/services/knowledge/RepositoryIntelligenceService.yaml, model/tools/list-files.yaml, model/tools/search-text.yaml, model/tools/read-range.yaml, docs/architecture/adr/0013-vector-store-profiles.md, docs/planes/knowledge-memory/services/repository-intelligence-service/index.md#apis

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-068 ListFiles, SearchText and ReadRange over the workspace view of the run implementation The three methods are handlers of the tool component that ToolExecutorHost runs in the sandbox of the run (D125); they take the request message of AIFACTORY-TASK-069, take the tenant, the project and the run from the scope and the runId of the invocation and validate no token, validate the arguments member of the invocation against the argument shape of their tool, open the workspace view of AIFACTORY-TASK-3292 from the workspaceRef member of the request only and answer from it alone: ListFiles pages the entries that match the path prefix, the name pattern and the depth, a link being an entry of kind link that is not followed; SearchText returns matches of the text, under the optional path prefix, as path and line range through the generic-text analyzer; ReadRange returns at most Knowledge:Repositories:MaxRangeLines lines of the path and names the range returned; every reply cites the workspaceRef and leaves revision empty; the methods keep nothing between calls, so a call after a write to the workspace returns the new state; they answer INVALID_ARGUMENT (also for arguments outside the shape of the tool and for a sandbox.workspaceId that differs from the workspaceRef), NOT_FOUND (for a workspace of another tenant by ADR-0015 and for one of another project or run by the rule of the view), UNAVAILABLE for a mounted workspace that cannot be read and, for a call that overruns the deadline the executor passes, DEADLINE_EXCEEDED as the PBI states, write nothing and count the call in connectsoft.factory.repo_intelligence.tool_calls without content. ConnectSoft.AI.SoftwareFactory.RepositoryIntelligenceService
AIFACTORY-TASK-3295 Verify the three file tools through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-RepositoryIntelligenceService-003\|Scenario=SCN-RepositoryIntelligenceService-004\|Scenario=SCN-RepositoryIntelligenceService-007)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-817 with the tool component over the sandbox fixtures of AIFACTORY-TASK-3293: the filtered and paged listing, the matches as ranges, the read after a write, in which a file is added and a line is changed between two calls and ListFiles, SearchText and ReadRange return the new entry, the new match and the changed line, the cap of ReadRange on a long file, the refusals with the fixture of two tenants, two projects and two runs, in which no call validates a token, the arguments outside the shape of a tool, the differing sandbox.workspaceId, the mount that cannot be read, the reads slowed beyond the deadline answered DEADLINE_EXCEEDED for each of the three methods and a scan of the captured logs, activities and metrics for query text and file lines. ConnectSoft.AI.SoftwareFactory.RepositoryIntelligenceService

AIFACTORY-US-818: Answer symbols, references and dependencies of the workspace of a run on demand, without an index

behavior · persona requester As a requester, I want the agents of my run to find a symbol, its references and the dependencies of a path in the code the run has written so far, so that a step changes the right place and knows what depends on it before any repository index exists.

An agent of the chain calls search-symbols, find-references or get-dependencies through ToolAdapterService. The call is executed inside the sandbox of the run, where ToolExecutorHost runs the read-tool component over the workspace mounted read-only (D125), and reaches RepositoryIntelligence.SearchSymbols, RepositoryIntelligence.FindReferences or RepositoryIntelligence.GetDependencies of the component with the invocation of tool-invocation-v1 and the workspaceRef of the run; the component validates no token, as AIFACTORY-US-817 states. The arguments of each tool are the arguments member of the invocation, in the shape the contract test of AIFACTORY-TASK-069 fixes: a name, a kind and a container for SearchSymbols, a symbol for FindReferences and a path or a symbol for GetDependencies. In the complete service these three tools read the entities SymbolEntry and DependencyEdge of a Ready index set. The thin delivery has no index set, so it writes no row to Symbols or DependencyEdges and computes each answer on demand from the files of the workspace view (AIFACTORY-US-816), with the language analyzers that Knowledge:Repositories:Analyzers enables, dotnet-roslyn, typescript and generic-text by default. The files of a workspace were written by agents of the run, and the analysis runs in the component inside the sandbox of the run, over a mount it cannot write to. It still reads source files and project files as data only, a reading D125 records for the on-demand analysis: it executes no target, no task and no script of the workspace, restores no package and makes no network call, because build and test are no part of this service (invariant of the model) and every read is bounded by the root of the workspace (AIFACTORY-US-816). A project reference, an import or a package path that resolves outside the root is not followed and is named in the partial mark of the reply. The version of a package edge is the version a file of the workspace declares; a package that only a restore would reveal is not reported. SearchSymbols returns symbols by name, kind and container, each in the shape of a symbol entry of the model: name, kind (namespace, type, member, method, property, field or event), path, start line, end line and container. FindReferences returns the references and the callers of one symbol as paths with line ranges. GetDependencies returns the edges of a path or a symbol in the shape of a dependency edge of the model: kind (project, package, call or test coverage), from, to and, for a package, its version. Answers are paged and name locations as ranges; the content of a location is read through ReadRange. A workspace is working state and may not compile. The analyzers answer from what parses and binds; when a project does not load or a file does not bind, the reply is marked partial and names the projects or paths that were not analysed, and a partial answer is never presented as complete. A path or a symbol in a language that no enabled analyzer covers yields an empty, well-formed result that names the language as not analysed. This is the thin form of the failure mode of the model in which an analyzer fails on a language or a project: no index set exists that could be set Failed, and SearchText, ListFiles and ReadRange keep answering because they need no language analyzer. How deep the on-demand analysis goes for a workspace that does not compile, bound semantics or syntax alone, is reported to the owner; the contract carries the partial mark either way. Every reply cites the workspaceRef and leaves revision empty. The three methods are of class read, write nothing and publish no event. Nothing of an analysis is kept after the call: the thin delivery holds no cache of an analysis, in memory or elsewhere, because the workspace view yields no state of a workspace by which a cache could be keyed. Each call analyses the workspace as it is at that moment, so a call made after a write tool of the run added or changed a symbol returns the new state and no entry of an earlier analysis; a stale symbol, reference or edge is the defect this rule excludes. A request without a workspaceRef, without the tenant, the project or the run in the invocation, without a symbol or a path to look for, with arguments that do not match the shape of the tool, with a sandbox.workspaceId in the invocation that differs from the workspaceRef, or with a path that leaves the workspace is refused with INVALID_ARGUMENT, and a workspaceRef, a tenant, a project or a run that is not the one of the lease that mounted the workspace with NOT_FOUND: for a workspace of another tenant as ADR-0015 amendment D113 decides, and for a workspace of another run or project of the same tenant and for an unknown reference by the rule of the workspace view (AIFACTORY-US-816), with the same reply in every case. An analysis that does not finish within the deadline of the call ends with DEADLINE_EXCEEDED and returns nothing as if complete; a mounted workspace that cannot be read ends the call with UNAVAILABLE. In both cases ToolAdapterService ends the tool call Failed with the failure class transient in its own PBI. Each call is counted in connectsoft.factory.repo_intelligence.tool_calls with tenant, project and tool, and no symbol name, path or source line reaches telemetry (ADR-0019).

Acceptance criteria

AC1 Given the fixture workspace with a .NET project and a TypeScript project, when RepositoryIntelligenceService/RepositoryIntelligence.SearchSymbols is called with a name, a kind and a container, then the reply holds the matching symbols of that workspace with name, kind, path, start line, end line and container, paged, with the workspaceRef and an empty revision, and no row exists in Symbols afterwards (SCN-RepositoryIntelligenceService-005, FR-05).
AC2 Given a method of the .NET project that two other files call, when RepositoryIntelligenceService/RepositoryIntelligence.FindReferences is called for that symbol, then the reply holds each reference and each caller as a path with its line range and no location outside the workspace, and a second call over the unchanged workspace returns the same locations; given a symbol with one caller added to a file of the fixture workspace between two calls, when RepositoryIntelligenceService/RepositoryIntelligence.SearchSymbols, RepositoryIntelligenceService/RepositoryIntelligence.FindReferences and RepositoryIntelligenceService/RepositoryIntelligence.GetDependencies are called again, then each reply holds the new state, the new symbol, its reference and its call edge, and no entry of the earlier analysis (SCN-RepositoryIntelligenceService-005, SCN-RepositoryIntelligenceService-006, SCN-RepositoryIntelligenceService-008, XL-03).
AC3 Given a project of the workspace that references another project and two packages and is covered by a test project, when RepositoryIntelligenceService/RepositoryIntelligence.GetDependencies is called for its path, then the reply holds the edges of kind project, package, call and test coverage with from, to and the package versions, and no row exists in DependencyEdges afterwards (SCN-RepositoryIntelligenceService-008, model/services/knowledge/RepositoryIntelligenceService.yaml).
AC4 Given a workspace in which one project does not load, one project file declares a target with a command and a project reference that leaves the root, and one file is written in a language no enabled analyzer covers, when the three methods are called, then each reply is marked partial and names the project that was not analysed and the reference that leaves the root, the command of the declared target did not run, no package was restored, no network call was made and nothing outside the root was read, the file of the uncovered language yields an empty, well-formed result that names the language, no partial answer is presented as complete, and RepositoryIntelligenceService/RepositoryIntelligence.SearchSymbols still answers for the projects that loaded (SCN-RepositoryIntelligenceService-005, SCN-RepositoryIntelligenceService-006, SCN-RepositoryIntelligenceService-008).
AC5 Given a request without a workspaceRef or without a symbol or path, a workspaceRef of another tenant or run, an analysis that exceeds the deadline of the call and a mounted workspace that cannot be read, when any of the three methods is called in the sandbox fixture, then the answer is INVALID_ARGUMENT, NOT_FOUND, DEADLINE_EXCEEDED or UNAVAILABLE respectively, no call validated a token, nothing is written, and no symbol name or source line reaches telemetry (SCN-RepositoryIntelligenceService-005, SCN-RepositoryIntelligenceService-006, SCN-RepositoryIntelligenceService-008, ADR-0015, ADR-0019).
Traces: services RepositoryIntelligenceService, ToolAdapterService
Traces: apis RepositoryIntelligenceService/RepositoryIntelligence.SearchSymbols, RepositoryIntelligenceService/RepositoryIntelligence.FindReferences, RepositoryIntelligenceService/RepositoryIntelligence.GetDependencies
Traces: tools search-symbols, find-references, get-dependencies
Traces: descriptors tool-invocation-v1
Traces: adrs ADR-0015, ADR-0019, ADR-0022
Traces: requirements FR-05, XL-03
Traces: scenarios SCN-RepositoryIntelligenceService-005, SCN-RepositoryIntelligenceService-006, SCN-RepositoryIntelligenceService-008
Depends on AIFACTORY-US-816, AIFACTORY-US-817, feature:component-base-template-factory-profile, feature:component-observability-factory-conventions
Sources model/services/knowledge/RepositoryIntelligenceService.yaml, model/tools/search-symbols.yaml, model/tools/find-references.yaml, model/tools/get-dependencies.yaml, docs/planes/knowledge-memory/services/repository-intelligence-service/index.md#failure-and-recovery

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-3296 SearchSymbols, FindReferences and GetDependencies computed on demand by the enabled analyzers over the workspace view implementation The three methods are handlers of the tool component that ToolExecutorHost runs in the sandbox of the run (D125); they take the request message of AIFACTORY-TASK-069, validate no token, validate the arguments member of the invocation against the argument shape of their tool, open the workspace view of AIFACTORY-TASK-3292 from the workspaceRef member of the request only and compute their answer per call with the analyzers of Knowledge:Repositories:Analyzers: symbols with name, kind, path, lines and container, references and callers as path and line range, edges of kind project, package, call and test coverage with from, to and version; the analysis reads source files and project files as data only: no target, task or script of the workspace is executed, no package is restored and no network call is made, the version of a package edge is the version a file of the workspace declares, and a project reference, import or package path that resolves outside the root is not followed and is named in the partial mark; answers are paged, cite the workspaceRef and leave revision empty; a project that does not load or a file that does not bind marks the reply partial with the unanalysed projects or paths named, a language without an analyzer yields an empty result that names it; nothing is written to Symbols or DependencyEdges and no cache of an analysis is held, in memory or elsewhere, so every call analyses the workspace as it is at that moment and a call after a write returns the new state; the methods answer INVALID_ARGUMENT, NOT_FOUND, DEADLINE_EXCEEDED and UNAVAILABLE as the PBI states and count the call in connectsoft.factory.repo_intelligence.tool_calls without content. ConnectSoft.AI.SoftwareFactory.RepositoryIntelligenceService
AIFACTORY-TASK-3297 Fixture projects for the analysis tools with known symbols, references, edges and a project that does not load fixture The fixture workspace of AIFACTORY-TASK-3293 is extended with a .NET project whose symbols, callers and references are listed in a golden file, a second .NET project it references, a test project that covers it, two package references with versions, a TypeScript project with exported symbols, a project file that does not load, a project file that declares a target with a command which would write a marker file if it ran and a project reference that leaves the root of the workspace toward a directory of the test host that holds a readable source file, and one source file in a language no enabled analyzer covers; the suite can add a symbol with one caller to a file of the fixture workspace between two calls; an analyzer double can be slowed beyond the deadline of a call; the test host records file reads outside the root and outbound network calls of the component process. ConnectSoft.AI.SoftwareFactory.RepositoryIntelligenceService
AIFACTORY-TASK-3298 Verify the three analysis tools through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-RepositoryIntelligenceService-005\|Scenario=SCN-RepositoryIntelligenceService-006\|Scenario=SCN-RepositoryIntelligenceService-008)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-818 against the golden file of the fixture projects: the symbols, the references and callers, the four kinds of edge, the read after a write, in which a symbol with one caller is added between two calls and SearchSymbols, FindReferences and GetDependencies return the new state and no entry of the earlier analysis, the partial mark for the project that does not load, the project file with a target and a reference that leaves the root, for which the marker file of the command does not exist, no read outside the root, no package restore and no network call was recorded and the reply is partial with the reference named, the empty result of the uncovered language, the refusals over the sandbox fixtures of two tenants, two projects and two runs, in which no call validates a token, the exceeded deadline, the mount that cannot be read, the empty tables Symbols and DependencyEdges and the scan of telemetry for symbol names and source lines. ConnectSoft.AI.SoftwareFactory.RepositoryIntelligenceService

AIFACTORY-US-819: Read the status and the diff of the workspace of a run through GetHistory, with an empty ownership part until an index exists

behavior · persona requester As a requester, I want the agents of my run to see which files the run changed and how, so that a step reviews the change of the run before a change set is proposed from it.

An agent of the chain calls get-git-diff through ToolAdapterService. The call is executed inside the sandbox of the run, where ToolExecutorHost runs the read-tool component over the workspace mounted read-only (D125), and reaches RepositoryIntelligence.GetHistory of the component with the invocation of tool-invocation-v1 and the workspaceRef of the run; the component validates no token, as AIFACTORY-US-817 states. The model gives this one method three reads: the diff, the status on the read side, and ownership, which is the history, the churn and the owners of a path. The catalogue entry of the tool, model/tools/get-git-diff.yaml, asks for the diff and the status of a workspace or between revisions. The thin delivery serves the part that a workspace can answer. The status lists the paths of the workspace that were added, modified, deleted or renamed against the base the workspace view reports (AIFACTORY-US-816). The diff returns, for the paths the request names or for all changed paths, the hunks of each change as line ranges with their lines; it is paged, and one answer holds at most Knowledge:Repositories:MaxRangeLines lines, so a large change is read in parts and never as one dump. The model defines that option as the maximum of lines a read_range answer returns and names no page size for a diff; its reuse as the page cap of a diff is a reading of the thin delivery and no model value, and it is reported to the owner with the open points of the reply contract. The optional paths are the arguments member of the invocation, in the shape the contract test of AIFACTORY-TASK-069 fixes. The base of a workspace is what the version control metadata of the mounted workspace records, the commit its working tree was checked out from; the view reads it from that metadata without writing to it (AIFACTORY-US-816), and the method takes the base from the view and decides nothing about it. The ownership part needs the entity OwnershipEntry of an index set, with last commit, last change, churn and owners per path. The thin delivery builds no index set, so that part of the reply is present, empty and well-formed, and the complete delivery fills it without a contract change. A request that names two revisions in place of a workspace is outside the thin scope, because the thin delivery holds no revision: it is refused with INVALID_ARGUMENT and a reason that says so. Every reply cites the workspaceRef and leaves revision empty. The method is of class read: it writes no row to Ownership, no artifact and no outbox record and publishes no event, it never changes the workspace or its version control state, and a repeated call over an unchanged workspace returns the same status and the same hunks, while a call made after a file changed returns the new status and hunks, because nothing is kept between calls. A request without a workspaceRef, without the tenant, the project or the run in the invocation, with arguments that do not match the shape of the tool, with a sandbox.workspaceId in the invocation that differs from the workspaceRef or with a path that leaves the workspace is refused with INVALID_ARGUMENT, and a workspaceRef, a tenant, a project or a run that is not the one of the lease that mounted the workspace with NOT_FOUND: for a workspace of another tenant as ADR-0015 amendment D113 decides, and for a workspace of another run or project of the same tenant and for an unknown reference by the rule of the workspace view (AIFACTORY-US-816), with the same reply in every case. A workspace that holds no version control metadata has no base: the status and the diff are then empty and well-formed and the reply says that the workspace has no base, so an empty diff is never mistaken for an unchanged workspace. When the mounted workspace cannot be read the method answers UNAVAILABLE. A call that does not finish within the deadline the executor passes, 30 seconds for get-git-diff in the catalogue, ends with DEADLINE_EXCEEDED and returns nothing as if complete, which a diff over a large workspace can reach. In both cases ToolAdapterService ends the tool call Failed with the failure class transient in its own PBI. Pushing the diff as a branch and opening a change proposal is the tool propose-change-set of ToolAdapterService behind its approval and is not served here (XL-10). The call is counted in connectsoft.factory.repo_intelligence.tool_calls with tenant, project and tool, and no path and no line of a diff reaches telemetry (ADR-0019).

Acceptance criteria

AC1 Given the fixture workspace with a base, one added, one modified and one deleted file, when RepositoryIntelligenceService/RepositoryIntelligence.GetHistory is called with the workspaceRef of the run, then the reply holds the three paths with their status against the base, the hunks of the two changed files as line ranges with their lines, the workspaceRef, an empty revision and an empty, well-formed ownership part, and the workspace and its version control state are unchanged (SCN-RepositoryIntelligenceService-009, FR-05).
AC2 Given a change larger than Knowledge:Repositories:MaxRangeLines, the option the thin delivery reuses as the page cap of a diff, when RepositoryIntelligenceService/RepositoryIntelligence.GetHistory is called, then one answer holds at most the cap and a continuation token, the following calls return the remaining hunks, and a second pass over the unchanged workspace returns the same status and hunks (SCN-RepositoryIntelligenceService-009, model/tools/get-git-diff.yaml).
AC3 Given a workspace without version control metadata, when the method is called, then status and diff are empty and well-formed and the reply states that the workspace has no base; given a request that names two revisions in place of a workspace, then it is refused with INVALID_ARGUMENT and the reason that the thin delivery holds no revision, as model/backlog/features/knowledge.yaml states its scope (SCN-RepositoryIntelligenceService-009).
AC4 Given a request without a workspaceRef or with a path that leaves the workspace, a workspaceRef of another tenant or of another project or run of the same tenant, a mounted workspace that cannot be read and reads of the mounted workspace that are slower than the deadline the executor passes, when the method is called in the sandbox fixture, then the answer is INVALID_ARGUMENT, NOT_FOUND, UNAVAILABLE or DEADLINE_EXCEEDED respectively, no call validated a token, nothing is returned as if complete, no row exists in Ownership, nothing is published, and no path or diff line reached telemetry (SCN-RepositoryIntelligenceService-009, ADR-0015, ADR-0019).
Traces: services RepositoryIntelligenceService, ToolAdapterService
Traces: apis RepositoryIntelligenceService/RepositoryIntelligence.GetHistory
Traces: tools get-git-diff
Traces: descriptors tool-invocation-v1
Traces: adrs ADR-0015, ADR-0019, ADR-0022
Traces: requirements FR-05, XL-10
Traces: scenarios SCN-RepositoryIntelligenceService-009
Depends on AIFACTORY-US-816, feature:component-base-template-factory-profile, feature:component-observability-factory-conventions
Sources model/services/knowledge/RepositoryIntelligenceService.yaml, model/tools/get-git-diff.yaml, model/backlog/features/knowledge.yaml, docs/planes/knowledge-memory/services/repository-intelligence-service/index.md#apis

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-3299 GetHistory over the workspace view with status, paged diff hunks and an empty ownership part implementation The method is a handler of the tool component that ToolExecutorHost runs in the sandbox of the run (D125); it takes the request message of AIFACTORY-TASK-069, validates no token, validates the arguments member of the invocation against the argument shape of get-git-diff (optional paths), opens the workspace view of AIFACTORY-TASK-3292 from the workspaceRef member of the request only and returns the status of the changed paths against the base the view reads from the version control metadata of the mounted workspace and the hunks of the named or of all changed paths as line ranges with their lines, paged with at most Knowledge:Repositories:MaxRangeLines lines per answer, a reuse of that option which is a reading of the thin delivery; nothing is kept between calls, so a call after a change returns the new status; the ownership part is present and empty; a workspace without a base yields an empty status and diff and the reply says so; a request that names revisions is refused with INVALID_ARGUMENT; the reply cites the workspaceRef and leaves revision empty; the method never changes the workspace, writes nothing to Ownership, answers INVALID_ARGUMENT, NOT_FOUND, UNAVAILABLE and, for a call that overruns the deadline the executor passes, DEADLINE_EXCEEDED as the PBI states and counts the call in connectsoft.factory.repo_intelligence.tool_calls without content. ConnectSoft.AI.SoftwareFactory.RepositoryIntelligenceService
AIFACTORY-TASK-3300 Verify the diff and the status of a workspace through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-RepositoryIntelligenceService-009"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-819 with the tool component over the sandbox fixtures of AIFACTORY-TASK-3293: the status and the hunks against the base, the paged large change, the workspace without a base, the refused request by revisions, the refusals over the sandbox fixtures of two tenants, two projects and two runs, in which no call validates a token, the mount that cannot be read, the reads slowed beyond the deadline answered DEADLINE_EXCEEDED, the new status and hunks of a call made after a file changed, the unchanged workspace after every call, the empty table Ownership and the scan of telemetry for paths and diff lines. ConnectSoft.AI.SoftwareFactory.RepositoryIntelligenceService