AIFACTORY-FEAT-018: ContextBuilderService: 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 62 of 185 (Factory code)
ContextBuilderService is the service of bounded context BC-09 (Context Assembly). The context engineering plane — plans what a task needs (mandatory instructions, task, conversation state, repository state, knowledge, graph neighbours, episodic memory, diff, tool results), retrieves and expands candidates, ranks, deduplicates, compresses and budgets tokens, and records an immutable context snapshot that says what was used and why (BC-09). In this increment it is delivered thin: Passes the pinned artifacts of a step through as its context package; no budget, ranking or provenance. Its own repository is ConnectSoft.AI.SoftwareFactory.ContextBuilderService.
| Delivers | ContextBuilderService (thin): Passes the pinned artifacts of a step through as its context package; no budget, ranking or provenance. |
| Stubs | — |
| Realizes | adrs: ADR-0013, ADR-0014, ADR-0019 |
| Requirements | FR-07, FUX-06, FUX-09, NFR-03, NFR-07, NFR-11, NFR-16, XL-03, XL-07 |
| Depends on | — |
| Sources | model/services/knowledge/ContextBuilderService.yaml |
Scenarios to trace (4, catalog): SCN-ContextBuilderService-001, SCN-ContextBuilderService-002, SCN-ContextBuilderService-003 ✓, SCN-ContextBuilderService-004
AIFACTORY-US-060: ContextBuilderService answers the chain with its thin contract¶
behavior · persona requester
As a requester, I want ContextBuilderService to hand an attempt of my run the pinned artifacts of its step as a well-formed context package, so that an agent starts with exactly the inputs its step pins, and the Context Assembly context has one owner behind a contract that does not change later.
This is the integration PBI of the thin delivery. ContextBuilderService is the context engineering plane of bounded context BC-09: in its complete form it plans what a task needs, retrieves and expands candidates, ranks, deduplicates, compresses and budgets them and records an immutable context snapshot that says what was used and why. In this increment it is delivered thin, and the thin scope is exactly this: the service passes the pinned artifacts of a step through as its context package, with no budget, no ranking and no provenance. It has one caller, AgentRuntimeService, the only inbound gRPC caller the model lists, which asks ContextAssembly.Assemble when an attempt builds its context. The service hosts that one internal gRPC method (AIFACTORY-US-794) on the repository and the surface of AIFACTORY-US-793. Nothing else is served. No plan is made, nothing is retrieved from VectorMemoryService, no promoted memory and no repository state is read, and nothing is compressed, counted against a token budget, ranked, deduplicated or dropped. No ContextSnapshot is recorded: the aggregate is the record of provenance and budget, and its invariant never includes an item without provenance, which is exactly what the thin scope leaves out. So ContextAssembled is not published, the two REST reads ListContextSnapshots and GetContextSnapshot are not hosted, the tables ContextSnapshots and ContextItems are not created and none of the eleven consumed events is subscribed. All of that arrives with feature context-builder-service-complete in I5. The thin service calls no dependency. The pinned artifacts stay in ArtifactService, where the runtime reads each by its reference under its own workload token and where the tenant boundary of that read is enforced; no content passes through this service, so it takes no classification or redaction decision and stores nothing by hash. What this PBI proves beyond the suites of the two other PBIs is that hand-over on deployed instances: a task contract and its input documents are stored in the deployed ArtifactService (feature artifact-service), the Assemble request is built from the inputs of the stored contract, and every reference the package returns is fetched from ArtifactService with the hash its store reply stated; the service itself still calls no dependency, the suite does. The repository is scaffolded from the pinned base template package with UseFactoryProfile, so token validation, the scope chain, health, readiness and the telemetry wiring come from the profile and are not written again. The contract has two open points, which are reported to the owner, and the thin delivery makes it checkable without deciding them. The model names context-snapshot-v1 as the request and as the reply descriptor of the method, and model/descriptors.yaml lists no descriptor of that id: it lists context-package-v1, described by docs/reference/schemas/context-snapshot.schema.json. And that schema requires snapshotId, budget and, for every item, sourceRevision, chunkId, tokens and rank, which is what the thin scope excludes, and it allows no additional property. The proto therefore fixes two messages by golden files. The request message names the run, the attempt, the step and the pinned artifacts of the step as the task contract lists them under inputs, each with name, descriptor and reference; the model defines no request shape, so this one is fixed here. The reply message carries runId, attemptId, the trusted scope, one item per pinned artifact in the order of the request and a hash over the package; the members of the snapshot, of the budget and of ranking and provenance exist in the message and are unset in the thin delivery, and the contract test asserts which members are set and which are not. The complete delivery fills the same reply message, so it replaces the thin delivery without a change of the two messages. A caller without a workload identity is refused before any handler runs. Repository: ConnectSoft.AI.SoftwareFactory.ContextBuilderService.
Acceptance criteria
| AC1 | Given the repository ConnectSoft.AI.SoftwareFactory.ContextBuilderService scaffolded with dotnet new connectsoft-base -n ConnectSoft.AI.SoftwareFactory.ContextBuilderService --UseFactoryProfile true from the pinned template package, when its pipeline runs, then the solution builds, the unit and acceptance tests pass with complete reports and a container image is published (ADR-0028, model/services/knowledge/ContextBuilderService.yaml). |
| AC2 | Given the published images of the thin service and of ArtifactService deployed in the acceptance environment, and an agent-task-contract-v1 document and the documents its inputs name stored through ArtifactService/Artifacts.Store under one tenant and project, when an Assemble request built from the inputs of that stored task contract is sent to ContextBuilderService/ContextAssembly.Assemble on the deployed instance with a workload token of the identity authority of that environment, then the reply is the context package of exactly those inputs in the order of the request, and each reference the package returns is fetched through ArtifactService/Artifacts.Fetch from the deployed ArtifactService with the bytes and the hash its store reply stated, while a workload that forwards another tenant is answered NOT_FOUND for the same reference. |
| AC3 | Given the service descriptor of the thin delivery, when the contract test compares it with the hosted surface, then exactly ContextBuilderService/ContextAssembly.Assemble is hosted, no REST operation answers, the OrleansMessaging section declares no published event and no subscription, no table of model/services/knowledge/ContextBuilderService.yaml exists in context-builder-sql, and the test fails when an operation outside the thin scope appears. |
| AC4 | Given a call without a workload identity or with a token that lacks the service scope, when it reaches ContextBuilderService/ContextAssembly.Assemble, then it is refused before any handler runs and nothing is read (ADR-0015); given the service starts, when liveness and readiness are probed, then liveness answers and readiness is unready until the store is migrated, the silo has started and the identity authority is reachable. |
| Traces: services | ContextBuilderService, ArtifactService |
| Traces: apis | ContextBuilderService/ContextAssembly.Assemble, ArtifactService/Artifacts.Store, ArtifactService/Artifacts.Fetch |
| Traces: descriptors | context-package-v1, agent-task-contract-v1 |
| Traces: adrs | ADR-0015, ADR-0028 |
| Depends on | AIFACTORY-US-793, AIFACTORY-US-794, feature:component-base-template-factory-profile, feature:component-base-template-findings, feature:artifact-service |
| Sources | model/services/knowledge/ContextBuilderService.yaml, model/services/knowledge/ArtifactService.yaml, model/backlog/features/knowledge.yaml, model/descriptors.yaml, docs/reference/schemas/context-snapshot.schema.json, docs/reference/schemas/agent-task-contract.schema.json, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-063 Contract of the thin surface: service descriptor and proto of ContextAssembly.Assemble with golden request and reply messages |
contract | The service descriptor file of the repository lists exactly ContextAssembly.Assemble, internal, without streaming and of class read. The proto fixes the request message (run, attempt, step, the optional token limit and the pinned artifacts of the step, each with name, descriptor and reference, as agent-task-contract-v1 lists them under inputs) and the reply message (runId, attemptId, the scope, one item per pinned artifact in request order and the hash of the package, with the members of the snapshot, of the budget and of ranking and provenance present in the message and unset). A contract test with golden files asserts the set and the unset members and compares the names of the set members with docs/reference/schemas/context-snapshot.schema.json; it does not validate a thin reply against the whole schema, which requires the members the thin scope excludes, 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 the caller runs against this service without a fake and the complete delivery fills the same messages. | ConnectSoft.AI.SoftwareFactory.ContextBuilderService |
AIFACTORY-TASK-761 Verify context-builder-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, and dotnet test -c Release --filter "Category=Acceptance&Feature=ThinContextHandOver" against the instances of ContextBuilderService and ArtifactService deployed in the acceptance environment, where the suite stores an agent-task-contract-v1 document and its input documents through Artifacts.Store, builds the Assemble request from the inputs of the stored task contract, calls ContextAssembly.Assemble over the network with a workload token of the identity authority of that environment and fetches every returned reference through Artifacts.Fetch with the hash its store reply stated; a run that discovers no test and a zero-match filter count as failures; the runs pass and prove AC1 to AC4 of AIFACTORY-US-060, that is the scaffold and the published image, the pass-through package of SCN-ContextBuilderService-003 handed over on the deployed instances, the thin surface with no REST operation, no event, no subscription and no table of the model, the golden files of the request and reply messages, readiness and the refusal of a caller without workload identity. |
ConnectSoft.AI.SoftwareFactory.ContextBuilderService |
AIFACTORY-US-793: ContextBuilderService repository: scaffolded from the base template with the Factory profile, hosting one gRPC method and nothing else of the model¶
enabling
ContextBuilderService has its own repository, ConnectSoft.AI.SoftwareFactory.ContextBuilderService, its own deployable and its own store (ADR-0028). The repository is created and scaffolded in I0 by AIFACTORY-TASK-061 of feature repository-and-pipeline-conventions (D140), by the steps of its repository checklist, and this feature starts from that scaffold; its first commit is the unchanged output of dotnet new connectsoft-base -n ConnectSoft.AI.SoftwareFactory.ContextBuilderService --UseFactoryProfile true, generated from the template package at the version the gate of feature component-base-template-factory-profile published, with the messaging service name context-builder, the default of OrleansMessaging:ServiceName in the model. On that scaffold the thin delivery adds one thing and leaves out the rest on purpose. The service descriptor file lists exactly one operation, the internal gRPC method ContextAssembly.Assemble, without streaming and of class read, behind the workload policy of the service scope that names ContextBuilderService; the contract test of the profile compares the hosted endpoints with that file in both directions, so neither REST read of the model answers. The store context-builder-sql holds only what the scaffold of the profile creates for the messaging profile; the tables ContextSnapshots and ContextItems are created by the complete delivery, and the cache the model lists for built packages is not used, because the thin package is computed from its request alone. The OrleansMessaging section declares no published event and no subscription, so ContextAssembled is never written and no event of VectorMemoryService, KnowledgeIngestionService, MemoryPromotionService, RepositoryIntelligenceService, AuditService or RetentionResidencyService reaches a handler. The options DefaultBudgetTokens, PackageTtlSeconds, SectionBudgets and CompressionProfile of the section Knowledge:Context are not bound, because the thin delivery has no budget, no cache, no section and no compression; OrleansMessaging:ServiceName is bound. The one secret of the model, messaging-transport, reaches the service as a secret reference of the key vault, and the service is unready while it cannot be resolved. Telemetry is the wiring of the profile with two of the four instruments of the model: connectsoft.factory.context.assemblies counts each returned package by tenant and by the status Assembled, and connectsoft.factory.context.assembly_latency records its duration, both created through the instrument helper with tenant and project by default. connectsoft.factory.context.tokens_used and connectsoft.factory.context.dropped_items are not created, because the thin delivery counts no token and drops no item, and a series of zeros would read as a budget that was kept. Activities and log records carry tenant and project and the run, the step and the attempt of the request, and no content, which the service never holds (ADR-0019). Readiness is unready until the store is migrated, the silo has started and the identity authority is reachable.
Acceptance criteria
| AC1 | Given the repository created and scaffolded in I0 by AIFACTORY-TASK-061 of feature repository-and-pipeline-conventions, whose first commit is the unchanged output of dotnet new connectsoft-base -n ConnectSoft.AI.SoftwareFactory.ContextBuilderService --UseFactoryProfile true from the template package at its published version with the messaging service name context-builder, when the pipeline of the repository runs with the work of this feature, then the solution builds, the generated tests pass with complete reports and a container image is published (ADR-0028). |
| AC2 | Given the service descriptor file and the hosted surface, when the contract test of the profile runs, then exactly ContextBuilderService/ContextAssembly.Assemble is hosted as an internal gRPC method of class read behind the workload policy, a call to the route of either REST read of model/services/knowledge/ContextBuilderService.yaml finds no endpoint, and the test fails on an endpoint the file does not name. |
| AC3 | Given the migrated context-builder-sql and the configuration of the service, when they are inspected, then neither ContextSnapshots nor ContextItems exists, the OrleansMessaging section declares no published event and no subscription, the outbox holds no record after any call, and no option of Knowledge:Context is bound (model/backlog/features/knowledge.yaml). |
| AC4 | Given a start without a resolvable secret reference for messaging-transport, when readiness is probed, then the service is unready and names the reference; and given handled calls, when the collected telemetry is read, then connectsoft.factory.context.assemblies and connectsoft.factory.context.assembly_latency carry tenant and project, the instruments of token use and of dropped items do not exist, and every activity and log record carries run, step and attempt and no content (ADR-0019). |
| Traces: services | ContextBuilderService |
| Traces: apis | ContextBuilderService/ContextAssembly.Assemble |
| Traces: adrs | ADR-0019, ADR-0028 |
| Depends on | feature:component-base-template-factory-profile, feature:component-base-template-findings, feature:repository-and-pipeline-conventions, feature:component-observability-factory-conventions |
| Sources | model/services/knowledge/ContextBuilderService.yaml, model/backlog/features/knowledge.yaml, docs/planes/knowledge-memory/services/context-builder-service/index.md#apis, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-3184 Thin host of ContextBuilderService with one gRPC method, no messaging declaration and two of the four instruments |
implementation | The host maps ContextAssembly.Assemble behind the workload policy of the service scope and no REST route; the OrleansMessaging section holds the service name context-builder and declares no published event and no subscription; the migrations create no table of model/services/knowledge/ContextBuilderService.yaml and the cache is not configured; the options of Knowledge:Context are not bound; messaging-transport is read as a secret reference and a missing reference keeps the service unready; the enrichment registration of the pinned observability libraries is called once; connectsoft.factory.context.assemblies and connectsoft.factory.context.assembly_latency are created through the instrument helper, and the instruments of token use and of dropped items are not created. | ConnectSoft.AI.SoftwareFactory.ContextBuilderService |
AIFACTORY-TASK-3185 Verify the repository and the thin surface of ContextBuilderService |
verification | Run dotnet build -c Release and dotnet test -c Release --filter "Category=Acceptance&Feature=ThinSurface"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-793: the unchanged scaffold, the surface compared with the service descriptor in both directions, the absent tables, subscriptions and options of model/services/knowledge/ContextBuilderService.yaml, the empty outbox, the unready start without the secret reference, and the two instruments with tenant and project beside the two that do not exist. |
ConnectSoft.AI.SoftwareFactory.ContextBuilderService |
AIFACTORY-US-794: Return the pinned artifacts of a step as the context package of an attempt, unchanged and in order¶
behavior · persona requester
As a requester, I want the attempt of a step to receive exactly the artifacts the step pins, in their order and by reference, so that the first workflows run on their declared inputs before retrieval, ranking and budgets exist, and nothing reaches the agent that the step did not pin.
When an attempt builds its context, AgentRuntimeService asks ContextBuilderService for it through the internal gRPC method ContextAssembly.Assemble, without streaming and of class read. The runtime presents a workload token; such a token carries service scopes and no tenant claim, so the service reads the tenant and the project the runtime forwards only when the token holds the service scope that names ContextBuilderService (ADR-0015). The request names the run, the attempt, the step and the pinned artifacts of the step: the entries the task contract of the step (agent-task-contract-v1) lists under inputs, each with its name, its descriptor and its reference. The runtime may state the token limit of the attempt, which it takes from Runtime:Context:MaxContextTokens; the thin delivery applies no budget, so the value is accepted and ignored and nothing is cut. The reply is the context package: runId, attemptId, the trusted scope, one item per pinned artifact in the order of the request with name, descriptor and reference unchanged, and a hash over these members. Nothing is added, dropped, reordered, ranked, compressed or read. A step without pinned artifacts receives an empty package, which is no error. The service does not fetch the artifacts and does not check that a reference exists or belongs to the tenant: the runtime reads each from ArtifactService by its reference, and ArtifactService answers NOT_FOUND for an unknown reference and for one of another tenant alike, so the tenant boundary is enforced where the content is. The method writes nothing: no ContextSnapshot is recorded, no content is stored and no event is published, and the reply names no snapshot. The same request receives the same package with the same hash, so a runtime that lost the answer asks again and nothing changes. A call without a workload identity is refused with UNAUTHENTICATED, a token without the service scope with PERMISSION_DENIED, and a request without a run, without an attempt or with an entry that has no reference with INVALID_ARGUMENT; because nothing is addressed by identifier in this service, the thin method has no not-found answer. It reads no store and calls no dependency, so no outage of another service can fail it. When the service itself does not answer, the runtime, for which the dependency is of the degrade kind, retries within the budget of the attempt and ends the attempt Failed with the failure class transient when that budget is exhausted, as its own PBI states. connectsoft.factory.context.assemblies counts the package with the status Assembled, and the activity of the call carries run, step and attempt, the number of items and the hash of the package and never the content of an artifact (ADR-0019).
Acceptance criteria
| AC1 | Given a workload token that holds the service scope and forwards the tenant and the project of a run, and a request that names the run, the attempt, the step and three pinned artifacts with name, descriptor and reference, when ContextBuilderService/ContextAssembly.Assemble is called, then the reply carries runId, attemptId, the trusted scope, exactly three items in the order of the request with name, descriptor and reference unchanged and a hash over them, and nothing is written or published (SCN-ContextBuilderService-003). |
| AC2 | Given a request with a token limit far below the size of its pinned artifacts, a request without pinned artifacts and the same request sent twice, when ContextBuilderService/ContextAssembly.Assemble is called, then every pinned artifact is returned and none is cut, the empty request receives an empty package, the two replies carry the same hash, and no member of the snapshot, of the budget, of ranking or of provenance is set, as the thin scope of model/backlog/features/knowledge.yaml states (SCN-ContextBuilderService-003). |
| AC3 | Given a caller without a workload identity, a token without the service scope, or a request without a run, without an attempt or with an entry that has no reference, when ContextBuilderService/ContextAssembly.Assemble is called, then it is refused with UNAUTHENTICATED, PERMISSION_DENIED and INVALID_ARGUMENT respectively and no package is returned (SCN-ContextBuilderService-003, ADR-0015). |
| AC4 | Given the calls of the acceptance run, when the store, the outbox, the recording fakes of the dependencies of model/services/knowledge/ContextBuilderService.yaml and the collected telemetry are inspected, then no row and no outbox record was written, no dependency received a call, connectsoft.factory.context.assemblies rose once per returned package with the status Assembled, and no activity or log record holds content of an artifact (ADR-0019). |
| Traces: services | ContextBuilderService |
| Traces: apis | ContextBuilderService/ContextAssembly.Assemble |
| Traces: descriptors | context-package-v1, agent-task-contract-v1 |
| Traces: adrs | ADR-0015, ADR-0019 |
| Traces: scenarios | SCN-ContextBuilderService-003 |
| Depends on | AIFACTORY-US-793, feature:component-base-template-factory-profile |
| Sources | model/services/knowledge/ContextBuilderService.yaml, model/services/agent-mesh/AgentRuntimeService.yaml, docs/reference/schemas/agent-task-contract.schema.json, docs/reference/schemas/context-snapshot.schema.json |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-062 Implement the thin scope of ContextBuilderService for the first outcome |
implementation | ContextAssembly.Assemble takes the request message of AIFACTORY-TASK-063, reads the forwarded tenant and project only under the service scope, refuses a request without a run, without an attempt or with an entry that has no reference with INVALID_ARGUMENT, accepts and ignores a stated token limit, and returns the reply message with runId, attemptId, the trusted scope, one item per pinned artifact in request order with name, descriptor and reference unchanged and the hash of the package; it answers UNAUTHENTICATED and PERMISSION_DENIED as the PBI states, reads no store, calls no dependency, records no snapshot and writes no outbox record. It passes the pinned artifacts of a step through as its context package, with no budget, ranking or provenance; the contract matches the model, so the complete delivery replaces the thin one without a contract change. | ConnectSoft.AI.SoftwareFactory.ContextBuilderService |
AIFACTORY-TASK-3186 Assemble requests built from task contracts, workload tokens and recording fakes of the dependencies |
fixture | The acceptance suite holds agent-task-contract-v1 documents valid against docs/reference/schemas/agent-task-contract.schema.json with three inputs, with one input and with none, builders that turn their inputs into Assemble requests with and without a token limit, requests without a run, without an attempt and with an entry that has no reference, workload tokens with and without the service scope naming ContextBuilderService, recording fakes of the six outbound dependencies of model/services/knowledge/ContextBuilderService.yaml that fail the test when called, and a collector of metrics, activities and log records. | ConnectSoft.AI.SoftwareFactory.ContextBuilderService |
AIFACTORY-TASK-3187 Verify assemble-the-pinned-artifacts-of-a-step-as-its-context-package through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-ContextBuilderService-003"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-794: the package of three, of one and of no pinned artifact in request order, the ignored token limit, the equal hash of a repeated request, every refusal, the empty store and outbox, the dependencies that received no call and the telemetry scan. |
ConnectSoft.AI.SoftwareFactory.ContextBuilderService |