AIFACTORY-FEAT-021: VectorMemoryService: 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 65 of 185 (Factory code)
VectorMemoryService is the service of bounded context BC-11 (Retrieval & Indexes). The retrieval module (historical name kept from the June-2026 catalog) — vector, full-text, symbol, metadata, graph-projection and temporal retrieval combined under trusted scope with ACL enforced before top-k, citations with source version and index revision, embedding and index revisions pinned to profiles, and rebuildable derived indexes (BC-11, ADR-0013). In this increment it is delivered thin: The knowledge-search and graph-query tools answer with an empty, well-formed result; no index exists. Its own repository is ConnectSoft.AI.SoftwareFactory.VectorMemoryService.
| Delivers | VectorMemoryService (thin): The knowledge-search and graph-query tools answer with an empty, well-formed result; no index exists. |
| Stubs | — |
| Realizes | adrs: ADR-0005, ADR-0013 |
| Requirements | FR-07, FUX-09, NFR-03, NFR-07, NFR-16, XL-07 |
| Depends on | — |
| Sources | model/services/knowledge/VectorMemoryService.yaml |
Scenarios to trace (11, catalog): SCN-VectorMemoryService-001, SCN-VectorMemoryService-002, SCN-VectorMemoryService-003, SCN-VectorMemoryService-004, SCN-VectorMemoryService-005 ✓, SCN-VectorMemoryService-006 ✓, SCN-VectorMemoryService-007, SCN-VectorMemoryService-008, SCN-VectorMemoryService-009, SCN-VectorMemoryService-010, SCN-VectorMemoryService-011
AIFACTORY-US-063: VectorMemoryService answers the chain with its thin contract¶
behavior · persona requester
As a requester, I want VectorMemoryService to answer the knowledge tools of my run with an honest, well-formed empty result while no index exists, so that an agent of the chain can call its knowledge tools without failing and never receives an invented citation.
This is the integration PBI of the thin delivery. VectorMemoryService is the retrieval service of bounded context BC-11: in its complete form it combines vector, full-text, symbol, metadata, graph and temporal retrieval under a trusted scope, with the scope enforced by the backend before top-k and a citation on every item (ADR-0013). That form arrives with feature vector-memory-service-complete in I5. ADR-0013 decision 4 states that indexed retrieval is no prerequisite for the first governed workflow, and the first outcome ingests nothing. The thin scope is exactly this: the tools knowledge-search and graph-query answer with an empty, well-formed result, and no index exists. Both tools are owned by this service in the catalogue under model/tools, and every agent of the chain may call them through ToolAdapterService, the governed executor (ADR-0022 decision 2), whose executor forwards the invocation to the gRPC method of the tool. For knowledge-search the model names that method: Retrieval.Retrieve is the scoped retrieval for context assembly and for the knowledge-search tool. For graph-query the model names no gRPC method; Retrieval.ExpandGraph is the only graph method on the internal surface, and the REST operation QueryGraph has no route before the gateway of I3, so the thin delivery answers the tool through Retrieval.ExpandGraph and reports the gap to the owner. Whether a tool call needs an approval is decided by the policy decision of the executor pipeline alone; this service evaluates none and writes no audit evidence, because audit is the last stage of that pipeline. The caller presents a workload token, which carries service scopes and no tenant claim, so the service reads the tenant and the project the caller forwards only when the token holds the service scope that names VectorMemoryService (ADR-0015 amendment D114). The two internal methods are therefore admitted by the service scope alone. The model lists the scope factory.knowledge.read with the summary scoped search and graph query; a workload token holds service scopes only and cannot hold that scope, so factory.knowledge.read guards the public REST operations Search, QueryGraph and ListIndexRevisions of the complete delivery, and the wording of its summary is reported as a correction of the service file. Before it answers, each method resolves what the forwarded scope may retrieve from through Ingestion.GetSourceScope of KnowledgeIngestionService, a required, fail-fast dependency of the model whose thin delivery answers that call with no source and no collection (feature knowledge-ingestion-service-thin). The service makes that call under its own identity: it presents its own workload token, which holds the service scope that names KnowledgeIngestionService, forwards the tenant and the project of the incoming call and never forwards the token of its caller, whose service scope names this service and not that one (ADR-0015 amendment D114); the call is bounded by the deadline of the incoming call. The thin scope does not say whether the empty answer is given with or without that call; the delivery makes it, because a failed scope resolution must not read as an empty result, and reports the reading to the owner. The feature is delivered by two further PBIs, one per method (AIFACTORY-US-820 and AIFACTORY-US-821). Nothing else is served. The REST operations Search, QueryGraph, ListIndexRevisions and RebuildIndexes, the aggregates IndexRevision with its six transitions, GraphFact and RetrievalQuery, the five events, the workers IndexBuilder, GraphExtractor and BackendHealthProbe and the six 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 vector-memory-sql, records no RetrievalQuery, writes no outbox record and publishes no RetrievalExecuted, because the thin scope names the answer and nothing else. It binds no vector backend: Knowledge:VectorProfile:Kind is not read, the secret vector-index is not referenced, and the contract test of ADR-0013 for the scope filter of a backend belongs to the complete delivery. It makes no model call: embedding through ModelGateway.Embed of ModelRouterService with the model profile embedding and reranking through ModelGateway.Rerank with the profile reranker are delivered in I1 behind ports of that service and are first called by the complete delivery, since there is nothing to embed or to rank. It calls ArtifactService for no citation payload, since there is no citation. The repository ConnectSoft.AI.SoftwareFactory.VectorMemoryService is created and scaffolded in I0 by AIFACTORY-TASK-070 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), so token validation, the scope chain with its 401, 403 and 404 answers, health, readiness, the messaging profile vector-memory and the telemetry wiring come from the profile; the profile writes the run event envelope of the pinned contracts package through the Orleans outbox in the transaction of a command, and the thin delivery, which has no command, leaves the outbox empty. The model names context-snapshot-v1 as the request and as the reply descriptor of both methods. model/descriptors.yaml lists no descriptor of that id; the schema docs/reference/schemas/context-snapshot.schema.json is registered there as context-package-v1 and describes the context package of one attempt, with no shape for a retrieval request or for cited candidates with ranking signals. That is reported to the owner, and the thin delivery makes its contract checkable without deciding it: the proto fixes the request and the reply message of each method, the reply with the citation members the invariant of the model requires on every item (source id, source version, chunk id, embedding profile version and index revision), and the thin delivery returns those lists empty, so the complete delivery fills the same messages. The request of each method carries typed members and no invocation of tool-invocation-v1, because Retrieval.Retrieve also serves context assembly, which makes no tool call. The executor of ToolAdapterService, the one caller of this increment, fills the typed members from the invocation of the tool: the scope from its scope member, the run from its runId and the rest from its arguments. For knowledge-search the query and the optional number of candidates of the arguments become the query and the number of candidates of Retrieval.Retrieve. For graph-query the query, the graph domains and the temporal filter of the arguments become the query, the graph domains and the temporal validity of Retrieval.ExpandGraph, and the entity list of that request stays empty. The contract test holds golden files of both calls as the executor makes them, so the claim that a caller runs against this service without a fake is proven for the caller that exists. Feature tool-adapter-service names no method of VectorMemoryService for either tool; that is reported to the owner. Each call is counted in connectsoft.factory.knowledge.retrievals and timed in connectsoft.factory.knowledge.retrieval_latency through the helper of the pinned observability library, which puts the tenant and the project on the instruments. The model gives the counter the dimensions tenant, indexKinds and outcome: indexKinds is recorded empty in the thin delivery, because no index exists, and the outcome values of this delivery are empty and failed. No query text reaches a log record, an activity or a metric (ADR-0019).
Acceptance criteria
| AC1 | Given the repository ConnectSoft.AI.SoftwareFactory.VectorMemoryService created and scaffolded in I0 by AIFACTORY-TASK-070 of feature repository-and-pipeline-conventions, whose first commit is the unchanged output of dotnet new connectsoft-base -n ConnectSoft.AI.SoftwareFactory.VectorMemoryService --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/VectorMemoryService.yaml). |
| AC2 | Given a workload token that holds the service scope and a forwarded tenant and project, when VectorMemoryService/Retrieval.Retrieve and VectorMemoryService/Retrieval.ExpandGraph are called, then each resolves the scope through KnowledgeIngestionService/Ingestion.GetSourceScope with the own workload token of the service and never the token of its caller, and answers with the reply message the contract test fixes, holding no candidate, no fact, no citation and no index revision, as AIFACTORY-US-820 and AIFACTORY-US-821 prove one by one (ADR-0013, FR-07). |
| AC3 | Given the service descriptor of the thin delivery, when the contract test compares it with the hosted surface, then exactly VectorMemoryService/Retrieval.Retrieve and VectorMemoryService/Retrieval.ExpandGraph are hosted, no REST operation answers, the OrleansMessaging section declares no published and no consumed event, vector-memory-sql holds no row, no vector backend is bound and no call to a model profile is made, and the test fails when an operation outside the thin scope stated in model/backlog/features/knowledge.yaml appears. |
| AC4 | Given a call without a workload identity or with a token that lacks the service scope, when it reaches either method, then it is refused before any handler runs and nothing is resolved (ADR-0015); given the service starts, when liveness and readiness are probed, then liveness answers, readiness is ready once the identity authority is reachable, and the health detail names KnowledgeIngestionService with its state and no vector backend (model/services/knowledge/VectorMemoryService.yaml). |
| AC5 | Given calls of two tenants and two projects through both methods, when the metrics, the logs and the activities are read, then connectsoft.factory.knowledge.retrievals counts every call with its tenant, its project, the modelled dimension indexKinds recorded empty because no index exists, and its outcome, which is empty or failed in this delivery, connectsoft.factory.knowledge.retrieval_latency holds its duration, and no record holds query text or an entity name (ADR-0019, model/services/knowledge/VectorMemoryService.yaml). |
| Traces: services | VectorMemoryService, KnowledgeIngestionService |
| Traces: apis | VectorMemoryService/Retrieval.Retrieve, VectorMemoryService/Retrieval.ExpandGraph, KnowledgeIngestionService/Ingestion.GetSourceScope |
| Traces: tools | knowledge-search, graph-query |
| Traces: adrs | ADR-0005, ADR-0013, ADR-0015, ADR-0019, ADR-0022, ADR-0028 |
| Traces: requirements | FR-07 |
| Depends on | AIFACTORY-US-820, AIFACTORY-US-821, feature:repository-and-pipeline-conventions, feature:component-base-template-factory-profile, feature:component-base-template-findings, feature:component-observability-factory-conventions, feature:contracts-package, feature:knowledge-ingestion-service-thin |
| Sources | model/services/knowledge/VectorMemoryService.yaml, model/backlog/features/knowledge.yaml, model/descriptors.yaml, docs/reference/schemas/context-snapshot.schema.json, docs/architecture/adr/0013-vector-store-profiles.md, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, docs/planes/knowledge-memory/services/vector-memory-service/index.md#purpose-and-responsibilities |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-072 Contract of the thin surface: service descriptor and proto of Retrieve and ExpandGraph with citation members that stay empty, and the two calls as the tool executor makes them |
contract | The service descriptor file of the repository lists exactly Retrieval.Retrieve and Retrieval.ExpandGraph, both internal, unary and of class read. The request of each method carries typed members and no invocation of tool-invocation-v1, because Retrieve also serves context assembly, which makes no tool call. The proto fixes the request message of Retrieve (the forwarded scope as execution-scope-v1, the run, the query, the filters and the optional number of candidates asked for), the request message of ExpandGraph (the forwarded scope, the run, an optional list of entities, an optional query, the graph domains and the temporal validity) and one reply message per method: candidates with ranking signals and, per item, source id, source version, chunk id, embedding profile version and index revision for Retrieve, facts with provenance and trust tier and neighbours for ExpandGraph, and the list of index revisions used. The contract states the mapping the executor of feature tool-adapter-service applies when it fills the typed members from the invocation of a tool: the scope from the scope member and the run from the runId member of the invocation; for knowledge-search the query and the optional number of candidates of the arguments to the query and the number of candidates of Retrieve; for graph-query the query, the graph domains and the temporal filter of the arguments to the query, the graph domains and the temporal validity of ExpandGraph, with the entity list left empty. A contract test with golden files in this repository holds the two request and the two reply shapes and, beside them, two golden calls as the executor makes them, one of Retrieve for knowledge-search and one of ExpandGraph for graph-query with a query, the domain Code, a temporal filter and no entity; these two golden calls are named as the shapes the executor of feature tool-adapter-service calls, and the test asserts that the service accepts each and that the thin delivery returns every list empty; it does not validate a message against docs/reference/schemas/context-snapshot.schema.json, which describes a context package and not a retrieval, and that difference is the open point the PBI reports. The contract test of the Factory profile compares the hosted endpoints with the service descriptor file in both directions, so callers run against this service without a fake and the complete delivery fills the same messages without a contract change. | ConnectSoft.AI.SoftwareFactory.VectorMemoryService |
AIFACTORY-TASK-3301 Deployment values of the thin service: replica range, probes, messaging service name and the base address of the ingestion service |
operations | The deployment manifest states the replica range 2 to 10 of model/services/knowledge/VectorMemoryService.yaml, the liveness and readiness probes, the messaging service name vector-memory, the secret reference messaging-transport by name and never by value, and one base address for KnowledgeIngestionService from configuration; the workload identity of the service is the one the typed client of Ingestion.GetSourceScope presents, with the service scope that names KnowledgeIngestionService, and the manifest holds no credential by value; it references no vector-index secret, binds no vector backend and no base address of ModelRouterService or ArtifactService, which the thin delivery does not call; connectsoft.factory.knowledge.retrievals and connectsoft.factory.knowledge.retrieval_latency are registered through the helper of the pinned observability library with tenant and project; the modelled dimension indexKinds of the counter is recorded empty in the thin delivery and its outcome dimension takes the values empty and failed. | ConnectSoft.AI.SoftwareFactory.VectorMemoryService |
AIFACTORY-TASK-765 Verify vector-memory-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-063, that is the scaffold, both methods answered empty after the scope was resolved (SCN-VectorMemoryService-005, SCN-VectorMemoryService-006), the thin surface with its empty store, its empty messaging section, no vector backend and no model call, the golden files of the request and reply messages and of the two calls as the executor of feature tool-adapter-service makes them for knowledge-search and graph-query, the scope resolved with the own workload token of the service, the refusal of a caller without workload identity, the health detail and the telemetry conformance test over two tenants and two projects. |
ConnectSoft.AI.SoftwareFactory.VectorMemoryService |
AIFACTORY-US-820: Answer the knowledge-search tool through Retrieval.Retrieve with an empty, well-formed result under the resolved scope¶
behavior · persona requester
As a requester, I want a knowledge search of an agent of my run to return a well-formed result that holds nothing while nothing is indexed, so that the agent goes on with the artifacts of its step and is never handed a citation that no source backs.
An agent of the chain calls the tool knowledge-search, and the executor of ToolAdapterService forwards the invocation to the internal gRPC method Retrieval.Retrieve. The thin ContextBuilderService of this increment passes the pinned artifacts of a step through and makes no retrieval, so the tool is the only caller. The caller presents a workload token; the service reads the forwarded tenant and project only when the token holds the service scope that names VectorMemoryService (ADR-0015 amendment D114). The request message carries typed members that the executor fills from the invocation of the tool, the scope from its scope member, the run from its runId and the query and the optional number of candidates from its arguments (AIFACTORY-TASK-072). The method validates the request message and then resolves what that scope may retrieve from through Ingestion.GetSourceScope of KnowledgeIngestionService with the scope of the call as execution-scope-v1. It makes that call with its own workload token, which holds the service scope that names KnowledgeIngestionService, forwards the tenant and the project of the incoming call and never forwards the token of its caller, and it bounds the call by the deadline of the incoming call. The thin delivery of that service answers with no source and no collection. With nothing to retrieve from and no index in existence, the method consults no index, no vector backend and no model profile and returns the reply message with zero candidates, no citation and an empty list of index revisions used. The reply is well-formed: it is the same message the complete delivery returns, so a caller parses it without a special case, and it holds nothing that looks like a citation, which keeps the search honest (XL-07). The method is of class read. It writes no row, records no RetrievalQuery, writes no outbox record and publishes no RetrievalExecuted; a repeated call returns the same empty reply. A call without a workload identity is refused with UNAUTHENTICATED and a token without the service scope with PERMISSION_DENIED. A request without a query, without the tenant or the project in the forwarded scope or with a number of candidates below one is refused with INVALID_ARGUMENT; a request that names no number of candidates is valid, because the arguments of the tool need not name one. The request addresses no resource by identifier, so there is no not-found answer: isolation is that the scope is resolved under the forwarded tenant and project only and that the reply is computed from that resolution alone. KnowledgeIngestionService is a required, fail-fast dependency of the model, and an unresolved scope never reads as an empty result, because an empty result would say nothing is known while the scope was never resolved. When the dependency does not answer within the deadline, or answers UNAVAILABLE or DEADLINE_EXCEEDED, the method fails with UNAVAILABLE. When it refuses the credentials of this service, with UNAUTHENTICATED or PERMISSION_DENIED, or answers INVALID_ARGUMENT, INTERNAL or any other error, the method fails with INTERNAL, because a repeat of the call would not change the answer and the fault lies in this service or its configuration. In every one of these cases no empty reply is returned and the call is counted with the outcome failed. ToolAdapterService, for which this service is an optional dependency that degrades, then ends the tool call Failed in its own PBI, with the failure class transient for UNAVAILABLE, and a retry of the read is safe. The call is counted in connectsoft.factory.knowledge.retrievals with tenant, project, an empty indexKinds and the outcome empty or failed and timed in connectsoft.factory.knowledge.retrieval_latency; the query text reaches no log record, activity or metric (ADR-0019).
Acceptance criteria
| AC1 | Given a workload token that holds the service scope, a forwarded tenant and project and a query, when VectorMemoryService/Retrieval.Retrieve is called, then the scope is resolved once through KnowledgeIngestionService/Ingestion.GetSourceScope with execution-scope-v1, under the own workload token of the service, which holds the service scope that names KnowledgeIngestionService, with the tenant and the project of the call forwarded and without the token of the caller, the reply is the reply message of the contract with zero candidates, no citation and no index revision, and no index, vector backend or model profile was called (SCN-VectorMemoryService-005, ADR-0013, FR-07). |
| AC2 | Given the same call repeated, when both replies and the store are compared, then the replies are equal, vector-memory-sql holds no RetrievalQuery row and the outbox holds no record, because the thin scope stated in model/backlog/features/knowledge.yaml names the answer and nothing else (SCN-VectorMemoryService-005, XL-07). |
| AC3 | Given a caller without a workload identity, a token without the service scope, and a request without a query, without the forwarded tenant or project or with a number of candidates below one, when VectorMemoryService/Retrieval.Retrieve is called, then the call is refused with UNAUTHENTICATED, PERMISSION_DENIED or INVALID_ARGUMENT respectively, KnowledgeIngestionService/Ingestion.GetSourceScope is not called and nothing changes (SCN-VectorMemoryService-005, ADR-0015). |
| AC4 | Given KnowledgeIngestionService does not answer within the deadline of the call, or answers UNAVAILABLE or DEADLINE_EXCEEDED, when VectorMemoryService/Retrieval.Retrieve is called, then the call fails with UNAVAILABLE; given KnowledgeIngestionService/Ingestion.GetSourceScope answers PERMISSION_DENIED, UNAUTHENTICATED or another error, then the call fails with INTERNAL; in every one of these cases no empty result is returned in its place and the call is counted with the outcome failed; a repeated call after recovery returns the empty reply; connectsoft.factory.knowledge.retrievals counted every call with tenant, project and outcome and no query text reached telemetry (SCN-VectorMemoryService-005, ADR-0019, model/services/knowledge/VectorMemoryService.yaml). |
| Traces: services | VectorMemoryService, KnowledgeIngestionService, ToolAdapterService |
| Traces: apis | VectorMemoryService/Retrieval.Retrieve, KnowledgeIngestionService/Ingestion.GetSourceScope |
| Traces: tools | knowledge-search |
| Traces: descriptors | execution-scope-v1 |
| Traces: adrs | ADR-0013, ADR-0015, ADR-0019 |
| Traces: requirements | FR-07, XL-07 |
| Traces: scenarios | SCN-VectorMemoryService-005 |
| Depends on | feature:component-base-template-factory-profile, feature:component-observability-factory-conventions, feature:knowledge-ingestion-service-thin |
| Sources | model/services/knowledge/VectorMemoryService.yaml, model/services/knowledge/KnowledgeIngestionService.yaml, model/tools/knowledge-search.yaml, model/backlog/features/knowledge.yaml, docs/architecture/adr/0013-vector-store-profiles.md, docs/planes/knowledge-memory/services/vector-memory-service/index.md#apis |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-071 Retrieval.Retrieve of the thin scope with scope resolution and the empty reply |
implementation | Retrieval.Retrieve takes the request message of AIFACTORY-TASK-072, reads the forwarded tenant and project only under the service scope, validates the query and the optional number of candidates, resolves the source scope through a typed gRPC client of Ingestion.GetSourceScope and returns the reply message with zero candidates, no citation and no index revision; the typed client presents the own workload token of the service, which holds the service scope that names KnowledgeIngestionService, forwards the tenant and the project of the incoming call, never forwards the token of the caller and is bounded by the deadline of the incoming call; the method consults no index, no vector backend and no model profile, writes no RetrievalQuery row and no outbox record, answers UNAUTHENTICATED, PERMISSION_DENIED and INVALID_ARGUMENT before the scope is resolved, UNAVAILABLE when KnowledgeIngestionService does not answer within the deadline or answers UNAVAILABLE or DEADLINE_EXCEEDED, and INTERNAL when it refuses the credentials of this service or answers another error, returns no empty reply in any of these cases, and records connectsoft.factory.knowledge.retrievals, with indexKinds empty and the outcome empty or failed, and connectsoft.factory.knowledge.retrieval_latency without the query text. | ConnectSoft.AI.SoftwareFactory.VectorMemoryService |
AIFACTORY-TASK-3302 Fake of Ingestion.GetSourceScope for the acceptance suite |
fixture | The acceptance suite holds a fake of Ingestion.GetSourceScope of KnowledgeIngestionService that records the execution-scope-v1 it received, the forwarded tenant and project and the token that was presented, so a test can tell the own workload token of the service from the token of the caller, answers with no source and no collection as the thin delivery of that service does, can answer with one source to prove that the thin delivery still consults no index, can be switched to not answering and back, can answer slower than the deadline of a call, and can answer each of the statuses UNAVAILABLE, DEADLINE_EXCEEDED, UNAUTHENTICATED, PERMISSION_DENIED, INVALID_ARGUMENT and INTERNAL. | ConnectSoft.AI.SoftwareFactory.VectorMemoryService |
AIFACTORY-TASK-3303 Verify the knowledge-search answer through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-VectorMemoryService-005"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-820 with the fake of AIFACTORY-TASK-3302: the empty reply after one scope resolution, the token recorded by the fake equal to the own workload token of the service and different from the token of the caller, the equal repeat with an empty store and an empty outbox, the request without a number of candidates accepted, the three refusals without a call to the fake, the stopped fake, the slow fake and the fake that answers UNAVAILABLE or DEADLINE_EXCEEDED each answered UNAVAILABLE, the fake that answers PERMISSION_DENIED, UNAUTHENTICATED, INVALID_ARGUMENT or INTERNAL answered INTERNAL, no empty reply and the outcome failed in each of these cases, the fake that returns one source still answered empty, and the scan of telemetry for the query text. |
ConnectSoft.AI.SoftwareFactory.VectorMemoryService |
AIFACTORY-US-821: Answer the graph-query tool through Retrieval.ExpandGraph with an empty, well-formed result while no graph fact exists¶
behavior · persona requester
As a requester, I want a graph query of an agent of my run to return a well-formed result that holds no fact while no graph exists, so that the agent treats the graph as empty and never reasons from a relationship that no source backs.
An agent of the chain calls the tool graph-query, and the executor of ToolAdapterService forwards the invocation to a gRPC method of this service. The model names no method for the tool. Retrieval.ExpandGraph, which returns the neighbours of a set of entities in one or more graph domains with temporal validity, is the only graph method on the internal surface, and the REST operation QueryGraph has no route before the gateway of I3, so the thin delivery answers the tool through Retrieval.ExpandGraph; which method the tool calls once a federated query exists is reported to the owner. The catalogue entry model/tools/graph-query.yaml describes the tool as a federated query over graph domains with temporal filters and audits a query hash and the domains; it names no set of entities. The request message of Retrieval.ExpandGraph therefore carries typed members that the executor fills from the invocation of the tool (AIFACTORY-TASK-072): the scope from its scope member, the run from its runId, and from its arguments the query as the optional query member, the graph domains as the graph domains and the temporal filter as the temporal validity. The entity list of the request is optional and stays empty for a call made for the tool, so a graph-query call that carries a query and domains and no entity is a well-formed request and is answered with the empty reply. The thin delivery validates the query as a member and does not evaluate it, because no fact exists that it could match. The caller presents a workload token, and the service reads the forwarded tenant and project only when the token holds the service scope that names VectorMemoryService (ADR-0015 amendment D114). The method validates the request message and resolves what the scope may read through Ingestion.GetSourceScope of KnowledgeIngestionService, as Retrieval.Retrieve does, because a fact carries the source it was observed in. It makes that call with its own workload token, which holds the service scope that names KnowledgeIngestionService, forwards the tenant and the project of the incoming call and never forwards the token of its caller, and it bounds the call by the deadline of the incoming call. The thin delivery of that service answers with no source. No GraphFact exists: the worker GraphExtractor that derives facts from published chunks arrives with the complete delivery. The method therefore returns the reply message with zero facts and zero neighbours, each list present and empty, and nothing that carries provenance or a trust tier, because there is nothing to label (XL-07). The reply is the message the complete delivery returns, so a caller parses it without a special case. The method is of class read: it writes no row to GraphFacts, no outbox record and no GraphFactsUpdated, and a repeated call returns the same empty reply. A call without a workload identity is refused with UNAUTHENTICATED and a token without the service scope with PERMISSION_DENIED. A request without the tenant or the project in the forwarded scope, without a graph domain or with a domain that is none of the seven of the model (Code, Architecture, Infrastructure, Organization, Customer, Business, AgentExperience), or with a validity whose end lies before its start, is refused with INVALID_ARGUMENT. A request without an entity is not refused. Whether a graph-query call that names no domain is well-formed and means all seven domains is not stated by the catalogue entry and is reported to the owner; until then the domain list is required. The request addresses no stored resource by identifier, so there is no not-found answer; an entity that no fact names yields no neighbour and is not an error. KnowledgeIngestionService is the required, fail-fast dependency, and an unresolved scope never reads as an empty result. When it does not answer within the deadline, or answers UNAVAILABLE or DEADLINE_EXCEEDED, the method fails with UNAVAILABLE; when it refuses the credentials of this service, with UNAUTHENTICATED or PERMISSION_DENIED, or answers INVALID_ARGUMENT, INTERNAL or any other error, the method fails with INTERNAL. In every one of these cases no empty reply is returned and the call is counted with the outcome failed; ToolAdapterService then ends the tool call Failed in its own PBI, with the failure class transient for UNAVAILABLE. The call is counted in connectsoft.factory.knowledge.retrievals with tenant, project, an empty indexKinds and the outcome empty or failed and timed in connectsoft.factory.knowledge.retrieval_latency; no entity name and no query text reaches a log record, an activity or a metric (ADR-0019).
Acceptance criteria
| AC1 | Given a workload token that holds the service scope, a forwarded tenant and project, two entities and the graph domain Code, when VectorMemoryService/Retrieval.ExpandGraph is called, then the scope is resolved once through KnowledgeIngestionService/Ingestion.GetSourceScope under the own workload token of the service, with the tenant and the project of the call forwarded and without the token of the caller, the reply is the reply message of the contract with zero facts and zero neighbours, each list present and empty, and nothing is written (SCN-VectorMemoryService-006, ADR-0013, FR-07). |
| AC2 | Given the same call repeated, a call for an entity that no fact names, and the call the executor makes for the tool graph-query, with a query, the graph domain Code, a temporal filter and no entity, when the replies and the store are compared, then every reply is the same empty message and the call without an entity is not refused, GraphFacts holds no row and the outbox holds no record, as the thin scope stated in model/backlog/features/knowledge.yaml requires (SCN-VectorMemoryService-006, XL-07). |
| AC3 | Given a caller without a workload identity, a token without the service scope, and a request without a graph domain, with an unknown domain, with a validity that ends before it starts or without the forwarded tenant or project, when VectorMemoryService/Retrieval.ExpandGraph is called, then the call is refused with UNAUTHENTICATED, PERMISSION_DENIED or INVALID_ARGUMENT respectively, KnowledgeIngestionService/Ingestion.GetSourceScope is not called and nothing changes (SCN-VectorMemoryService-006, ADR-0015). |
| AC4 | Given KnowledgeIngestionService does not answer within the deadline of the call, or answers UNAVAILABLE or DEADLINE_EXCEEDED, when VectorMemoryService/Retrieval.ExpandGraph is called, then the call fails with UNAVAILABLE; given KnowledgeIngestionService/Ingestion.GetSourceScope answers PERMISSION_DENIED, UNAUTHENTICATED or another error, then the call fails with INTERNAL; in every one of these cases no empty result is returned in its place and connectsoft.factory.knowledge.retrievals counts the call with the outcome failed; a repeated call after recovery returns the empty reply, and no entity name and no query text reached telemetry (SCN-VectorMemoryService-006, ADR-0019, model/services/knowledge/VectorMemoryService.yaml). |
| Traces: services | VectorMemoryService, KnowledgeIngestionService, ToolAdapterService |
| Traces: apis | VectorMemoryService/Retrieval.ExpandGraph, KnowledgeIngestionService/Ingestion.GetSourceScope |
| Traces: tools | graph-query |
| Traces: descriptors | execution-scope-v1 |
| Traces: adrs | ADR-0013, ADR-0015, ADR-0019 |
| Traces: requirements | FR-07, XL-07 |
| Traces: scenarios | SCN-VectorMemoryService-006 |
| Depends on | AIFACTORY-US-820, feature:component-base-template-factory-profile, feature:component-observability-factory-conventions, feature:knowledge-ingestion-service-thin |
| Sources | model/services/knowledge/VectorMemoryService.yaml, model/services/knowledge/KnowledgeIngestionService.yaml, model/tools/graph-query.yaml, model/backlog/features/knowledge.yaml, docs/planes/knowledge-memory/services/vector-memory-service/index.md#apis |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-3304 Retrieval.ExpandGraph of the thin scope with scope resolution and the empty reply |
implementation | Retrieval.ExpandGraph takes the request message of AIFACTORY-TASK-072, reads the forwarded tenant and project only under the service scope, accepts an empty entity list and an optional query, as the executor sends them for the tool graph-query, validates the graph domains against the seven domains of the model and the temporal validity, resolves the source scope through the typed client of Ingestion.GetSourceScope and returns the reply message with zero facts and zero neighbours; the typed client presents the own workload token of the service, which holds the service scope that names KnowledgeIngestionService, forwards the tenant and the project of the incoming call, never forwards the token of the caller and is bounded by the deadline of the incoming call; the method writes no row to GraphFacts and no outbox record, answers UNAUTHENTICATED, PERMISSION_DENIED and INVALID_ARGUMENT (no graph domain, an unknown domain, a validity that ends before it starts, no forwarded tenant or project; never for a missing entity) before the scope is resolved, UNAVAILABLE when KnowledgeIngestionService does not answer within the deadline or answers UNAVAILABLE or DEADLINE_EXCEEDED, and INTERNAL when it refuses the credentials of this service or answers another error, returns no empty reply in any of these cases, and records connectsoft.factory.knowledge.retrievals, with indexKinds empty and the outcome empty or failed, and connectsoft.factory.knowledge.retrieval_latency without an entity name or the query text. | ConnectSoft.AI.SoftwareFactory.VectorMemoryService |
AIFACTORY-TASK-3305 Verify the graph-query answer through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-VectorMemoryService-006"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-821 with the fake of AIFACTORY-TASK-3302: the empty reply after one scope resolution, the token recorded by the fake equal to the own workload token of the service and different from the token of the caller, the equal repeat and the unknown entity with an empty GraphFacts table and an empty outbox, the golden call of the executor for graph-query with a query, the domain Code, a temporal filter and no entity answered with the empty reply, the refusals without a call to the fake, the stopped fake, the slow fake and the fake that answers UNAVAILABLE or DEADLINE_EXCEEDED each answered UNAVAILABLE, the fake that answers PERMISSION_DENIED, UNAUTHENTICATED, INVALID_ARGUMENT or INTERNAL answered INTERNAL, no empty reply and the outcome failed in each of these cases, and the scan of telemetry for entity names and the query text. |
ConnectSoft.AI.SoftwareFactory.VectorMemoryService |