AIFACTORY-FEAT-017: ArtifactService: complete delivery¶
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 61 of 185 (Factory code)
ArtifactService is the service of bounded context BC-12 (Artifacts & Lineage). The one authoritative writer of artifacts — immutable, hash-addressed content with metadata, classification, access scope, producing run and attempt, version chains and lineage to sources and inputs; previews and version history are projections (BC-12). Its own repository is ConnectSoft.AI.SoftwareFactory.ArtifactService.
| Delivers | ArtifactService (complete) |
| Stubs | — |
| Realizes | adrs: ADR-0014, ADR-0019 |
| Requirements | FR-08, FUX-06, NFR-03, NFR-05, NFR-16, XL-06, XL-14 |
| Depends on | — |
| Sources | model/services/knowledge/ArtifactService.yaml |
Scenarios to trace (13, catalog): SCN-ArtifactService-001 ✓, SCN-ArtifactService-002 ✓, SCN-ArtifactService-003 ✓, SCN-ArtifactService-004 ✓, SCN-ArtifactService-005 ✓, SCN-ArtifactService-006 ✓, SCN-ArtifactService-007 ✓, SCN-ArtifactService-008 ✓, SCN-ArtifactService-009 ✓, SCN-ArtifactService-010 ✓, SCN-ArtifactService-011 ✓, SCN-ArtifactService-012 ✓, SCN-ArtifactService-013 ✓
AIFACTORY-US-059: ArtifactService serves its scope end to end¶
behavior · persona requester
As a requester, I want every document my run depends on or produces stored once by hash with its producer, its lineage and its version chain, so that what a run used and produced can be read back, verified against its hash and explained later, and no other service holds content in its rows.
This is the integration PBI of the feature: it proves on a deployed instance that ArtifactService is the one place where the Factory keeps content. ArtifactService is the authoritative writer of bounded context BC-12: immutable content addressed by hash with metadata, classification, access scope, the producing run, attempt and agent, a version chain and lineage edges to its inputs; previews and version history are projections of the same rows and never a second copy. Every other service keeps a reference and a hash and never content (ADR-0019). In this increment the callers are services, not people. Each presents a workload token that holds the service scope naming ArtifactService and forwards the tenant and the project of its work; such a token carries no tenant claim, and the forwarded scope is read only under that service scope (ADR-0015). RunControlService stores the resolved execution snapshot of a run before it accepts the run, WorkflowEngineService stores the task contract of a step before it announces the step ready, AgentRegistryService stores the manifests and the authoring documents of its seeded releases for the platform tenant and names no project, BlueprintService and GenerationRecipeService store their documents and reports, ModelRouterService and ToolAdapterService store outputs, results and receipts, and AgentRuntimeService reads the task contract and the snapshot of an attempt by reference and stores checkpoints and produced artifacts. These are callers the model lists; this feature adds none. The proof of this PBI is the hand-over of the first outcome through the deployed service, and its criteria state only what a deployed instance can prove; what the repository suites of the other PBIs prove is not proven again here. A document stored once through Artifacts.Store is read through Artifacts.Fetch by another workload of the same tenant with the same bytes and the same hash, a repeated store leaves one artifact, and a workload that forwards another tenant is answered NOT_FOUND. A release manifest that a registry-shaped workload stores for the platform tenant without a project becomes a tenant-level artifact of that tenant, which has no project (D125), and is fetched by a workload of another tenant with the stated hash, because the read filter admits the tenant-level artifacts of the platform tenant for every tenant through Artifacts.Fetch (AIFACTORY-US-783, AIFACTORY-US-784); without that path the runtime and ModelRouterService, which work under the tenant of a customer, could not read the documents of the seeded releases, and the chain of the first outcome could not run. The hand-over survives a restart of the service, and ArtifactStored reaches a subscriber on the deployed transport once per stored document in the run event envelope of the contracts package. The repository, the aggregate and the store come from AIFACTORY-US-781, the hosted surface from AIFACTORY-US-782 and tenancy, secrets and telemetry from AIFACTORY-US-783. Storing (AIFACTORY-US-784), fetching (AIFACTORY-US-785), the validation verdict (AIFACTORY-US-786), the metadata, version and run reads (AIFACTORY-US-787), the preview (AIFACTORY-US-788), the deletion of content with the retention sweep (AIFACTORY-US-789), the export with the confirmation of a closing project (AIFACTORY-US-790) and the reference records that spare an artifact from the sweep (AIFACTORY-US-986) complete the delivery. The five REST operations are hosted and proven here. A person reaches them through the Knowledge gateway KnowledgeHost, which feature knowledge-host delivers in this increment and which is the only route by which a person reads or exports an artifact (D125); a user token carries the audience of that gateway, and this feature builds no direct route for a person. Of the eight consumed events of the model the feature registers the handlers of five: RunCompleted, RunFailed and RunCancelled of RunControlService, ProjectStateChanged of ProjectService and ClassificationChanged of AuditService. It also receives the audit evidence event AuditEvidenceSubmitted on audit.evidence.v1.evidence-submitted, which the model states as the command RecordEvidenceReference (AIFACTORY-US-986). The other three consumed events come from RetentionResidencyService, which is first delivered in I4: the handler of DeletionOrderIssued is built there with that service and is not registered here, and the handlers ApplyRetentionRule and ApplyLegalHold are not built either, because the store class a retention rule names and the scope a legal hold names are defined with that service. Until then no legal hold exists and no retention rule sets a project retention, so the default retention applies to every project artifact. The retention sweep is effective in this increment (D125): RetentionSweeper deletes content past the default of Knowledge:Artifacts:DefaultRetentionDays, one year (ADR-0019 decision 4), that no audit evidence record and no unexpired run references, as the reference records of the service tell, and a tenant-level artifact is no candidate (AIFACTORY-US-789). That no feature of the backlog builds the two handlers ApplyRetentionRule and ApplyLegalHold is reported to the owner. Repository: ConnectSoft.AI.SoftwareFactory.ArtifactService.
Acceptance criteria
| AC1 | Given the container image that the pipeline of the repository published (AIFACTORY-US-781), deployed in the acceptance environment with its secret references for artifact-blob and messaging-transport, when the instance starts against the artifact-sql, the blob store and the identity authority of that environment, then its readiness turns ready and the hand-over suite of this PBI calls that instance over the network and no in-process host; the scaffold, the hosted surface, tenancy and telemetry are proven by AIFACTORY-US-781, AIFACTORY-US-782 and AIFACTORY-US-783 and are not proven again here (ADR-0028, model/services/knowledge/ArtifactService.yaml). |
| AC2 | Given the deployed service and two workloads of one tenant and project, each with a workload token that holds the service scope, when the first stores a resolved-execution-snapshot-v1 document and an agent-task-contract-v1 document through ArtifactService/Artifacts.Store and the second reads each through ArtifactService/Artifacts.Fetch by the reference of the reply, then the bytes read have the content hash the reply stated and a repeated store of the same document in the same chain returns the same artifact and leaves one ArtifactService/Artifact; and when a registry-shaped workload stores a release-manifest-v1 document for the platform tenant without a project, then it is a tenant-level artifact of the platform tenant and a workload of another tenant fetches it with the hash the reply stated (ADR-0015). |
| AC3 | Given the stored documents of AC2 and a workload that forwards another tenant, when it calls ArtifactService/Artifacts.Fetch with the reference of a document of the first tenant, then the answer is NOT_FOUND exactly as for an unknown reference and no content is streamed; when it stores other content under the name of the release manifest without a project, then the artifact is written in its own tenant and the manifest of the platform tenant is unchanged; and a call without a workload identity is refused before any handler runs (ADR-0015). |
| AC4 | Given the documents of AC2 stored on the deployed instance, when the instance is restarted and the hand-over is repeated, then every document is fetched through ArtifactService/Artifacts.Fetch with the same bytes and the same hash, a repeated ArtifactService/Artifacts.Store of each returns the artifact stored before the restart, and no second ArtifactService/Artifact, blob or outbox record exists (ADR-0019). |
| AC5 | Given the subscriber of the fixture on artifacts.artifacts.v1.artifact-stored of the deployed transport, when the hand-over of AC2 and its repetition of AC4 have run, then it received exactly one ArtifactService/ArtifactStored per stored document in the run event envelope, the one of the release manifest without a projectId, because a tenant-level artifact has none, none for a repeated store and none that carries content (ADR-0014). |
| Traces: services | ArtifactService |
| Traces: aggregates | ArtifactService/Artifact |
| Traces: apis | ArtifactService/Artifacts.Store, ArtifactService/Artifacts.Fetch |
| Traces: events | ArtifactService/ArtifactStored |
| Traces: descriptors | artifact-v1, resolved-execution-snapshot-v1, agent-task-contract-v1, release-manifest-v1, run-event-envelope-v1 |
| Traces: adrs | ADR-0014, ADR-0015, ADR-0019, ADR-0028 |
| Traces: requirements | FR-08 |
| Relates: nfrs | NFR-05 |
| Depends on | AIFACTORY-US-781, AIFACTORY-US-782, AIFACTORY-US-783, AIFACTORY-US-784, AIFACTORY-US-785, AIFACTORY-US-786, AIFACTORY-US-787, AIFACTORY-US-788, AIFACTORY-US-789, AIFACTORY-US-790, AIFACTORY-US-986, feature:component-base-template-factory-profile, feature:component-base-template-findings, feature:contracts-package |
| Sources | model/services/knowledge/ArtifactService.yaml, model/backlog/features/knowledge.yaml, docs/planes/knowledge-memory/services/artifact-service/index.md, docs/architecture/adr/0019-data-governance.md, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-3151 Hand-over fixture of the first outcome for the deployed service |
fixture | The acceptance suite holds one resolved-execution-snapshot-v1 document and one agent-task-contract-v1 document valid against docs/reference/schemas/resolved-execution-snapshot.schema.json and docs/reference/schemas/agent-task-contract.schema.json, one Draft release manifest with the candidate fields of docs/reference/schemas/release-manifest.schema.json as AgentRegistryService seeds it, two workload identities of one tenant and project, one workload identity that forwards another tenant, and one registry-shaped workload identity that forwards the platform tenant of the environment and no project, each with a token that holds the service scope naming ArtifactService, a subscriber on artifacts.artifacts.v1.artifact-stored of the deployed transport that records every delivered envelope, and a step that restarts the deployed instance and waits for its readiness, so that the hand-over of AC2 to AC5 of AIFACTORY-US-059 runs against the deployed service without RunControlService, WorkflowEngineService, AgentRegistryService or AgentRuntimeService. | ConnectSoft.AI.SoftwareFactory.ArtifactService |
AIFACTORY-TASK-760 Verify artifact-service-serves-its-scope 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=ArtifactHandOver" against the deployed service; a run that discovers no test and a zero-match filter count as failures; the run against the deployed instance proves AC1 to AC5 of AIFACTORY-US-059, that is the readiness of the deployed image, the two documents stored once through ArtifactService/Artifacts.Store and read with the stated hash through ArtifactService/Artifacts.Fetch, the release manifest stored for the platform tenant without a project and fetched by a workload of another tenant, NOT_FOUND for the workload of another tenant and its store that leaves the platform document unchanged, the hand-over repeated after a restart, and exactly one ArtifactStored per stored document on the deployed transport; the thirteen scenarios SCN-ArtifactService-001 to SCN-ArtifactService-013 are proven by the suites of AIFACTORY-US-784 to AIFACTORY-US-790, and the reference records by the suite of AIFACTORY-US-986. |
ConnectSoft.AI.SoftwareFactory.ArtifactService |
AIFACTORY-US-781: ArtifactService repository: scaffolded from the base template with the Factory profile, with the Artifact aggregate and the store artifact-sql¶
enabling
ArtifactService has its own repository, ConnectSoft.AI.SoftwareFactory.ArtifactService, its own deployable and its own stores (ADR-0028). The repository is created and scaffolded in I0 by AIFACTORY-TASK-054 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.ArtifactService --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 artifact, the default of OrleansMessaging:ServiceName in the model. Token validation, the scope chain with its 401, 403 and 404 answers, the tenant row filter, health, readiness and the telemetry wiring come from the profile and are not written again; the repository pins the contracts package, from which it takes the run event envelope, the topic constants and the event types. On that scaffold this PBI builds the domain model and the relational store and delivers no behaviour of an operation. The aggregate Artifact of the model has twenty-three fields. This PBI builds twenty of them, from artifactId, tenantId and the optional projectId, which is absent for a tenant-level artifact (D125), over kind, name, contentHash, contentRef, sizeBytes, mediaType, classification, accessScope and the optional descriptor to the optional producer (producerRunId, producerAttemptId, producerAgentId), chainId, versionInChain, state, the optional validationRef and createdAt, with the entity LineageEdge (input kind, input reference, relation). The other three fields, passed, finalOutput and pendingRemoval, and the entities ArtifactReference and ExportRequest are in the model as well (D125) and are built with their columns and tables by the PBIs that deliver their behaviour: AIFACTORY-US-786, AIFACTORY-US-787, AIFACTORY-US-789, AIFACTORY-US-986 and AIFACTORY-US-790. The aggregate has the enums ArtifactKind, whose eleven values include Prompt and ModelOutput so that content never lives in the rows of another service, and ArtifactState. The state machine has exactly the six transitions of the model: Stored to Validated on ValidationRecorded, Stored to Superseded and Validated to Superseded on NewVersionStored, and Stored, Validated and Superseded to Deleted on Delete. The aggregate refuses every other pair: nothing leaves Deleted, a Superseded artifact is never Validated and a Validated artifact never returns to Stored. The invariants hold in the aggregate: the content members contentHash, contentRef, sizeBytes and mediaType cannot change after creation, a new content hash is a new artifact with the next versionInChain of its chain, and Delete clears neither metadata nor a lineage edge. The store artifact-sql has five tables in the model. This PBI creates three of them, VersionChains, Artifacts and LineageEdges, with the columns of the twenty fields, the foreign keys, the unique indexes UX_Chains_Project_Name and UX_Artifacts_Chain_Version and the indexes IX_Artifacts_Tenant_Hash, IX_Artifacts_ProducerRun and IX_Lineage_Input. ProjectId is nullable in Artifacts and in VersionChains and is empty for a tenant-level artifact and for its chain, and UX_Chains_Project_Name covers TenantId, ProjectId and Name, so that the chain of a tenant-level artifact is found by tenant and name and tenant-level chains of two tenants with the same name do not collide (D125). The columns Passed, FinalOutput and PendingRemoval of Artifacts, the column Closed of VersionChains and the tables ArtifactReferences and ExportRequests are created by the migrations of the PBIs named above. Every table has the tenant column and every mapping carries the tenant row filter of the profile. No column holds content: a row holds the hash and the reference of a blob in artifact-blob. Mapping tests run against an isolated test database, never a shared one.
Acceptance criteria
| AC1 | Given the repository created and scaffolded in I0 by AIFACTORY-TASK-054 of feature repository-and-pipeline-conventions, whose first commit is the unchanged output of dotnet new connectsoft-base -n ConnectSoft.AI.SoftwareFactory.ArtifactService --UseFactoryProfile true from the template package at its published version with the messaging service name artifact, 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 aggregate ArtifactService/Artifact, when each of the six transitions of model/services/knowledge/ArtifactService.yaml is applied from its listed source state, then it succeeds, and every other pair of states, a transition out of Deleted, Superseded to Validated and Validated to Stored among them, is refused with the artifact unchanged. |
| AC3 | Given an empty artifact-sql, when the migrations run, then VersionChains, Artifacts and LineageEdges exist with the columns of the twenty fields, the keys and the indexes of docs/planes/knowledge-memory/services/artifact-service/ddl.md, ProjectId accepts an empty value in Artifacts and in VersionChains, a second row with the same ChainId and VersionInChain and a second chain with the same TenantId, ProjectId and Name, two chains of one tenant with an empty ProjectId and the same name included, are refused by their unique indexes, chains of two tenants with an empty ProjectId and the same name are both accepted, and rows of two tenants read under the scope of one tenant return only the rows of that tenant. |
| AC4 | Given a created ArtifactService/Artifact, when a change of contentHash, contentRef, sizeBytes or mediaType is attempted through the aggregate, then it is refused, and no table of artifact-sql has a column that holds content, so that content exists only in artifact-blob under its hash (ADR-0019). |
| Traces: services | ArtifactService |
| Traces: aggregates | ArtifactService/Artifact |
| Traces: adrs | ADR-0019, ADR-0028 |
| Traces: requirements | FR-08 |
| Depends on | feature:component-base-template-factory-profile, feature:component-base-template-findings, feature:contracts-package, feature:repository-and-pipeline-conventions |
| Sources | model/services/knowledge/ArtifactService.yaml, docs/planes/knowledge-memory/services/artifact-service/ddl.md, docs/planes/knowledge-memory/services/artifact-service/index.md#data-model-and-storage, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-055 Domain model: the Artifact aggregate with LineageEdge, ArtifactKind, ArtifactState and its six transitions |
implementation | The aggregate Artifact with twenty of the twenty-three fields of model/services/knowledge/ArtifactService.yaml, projectId being optional and absent for a tenant-level artifact (D125), the entity LineageEdge and the enums ArtifactKind and ArtifactState; the fields passed, finalOutput and pendingRemoval and the entities ArtifactReference and ExportRequest are built by AIFACTORY-US-786, AIFACTORY-US-787, AIFACTORY-US-789, AIFACTORY-US-986 and AIFACTORY-US-790; the six transitions under their triggers ValidationRecorded, NewVersionStored and Delete and the refusal of every other pair of states; the content members are immutable after creation and Delete keeps metadata and lineage edges; unit tests cover every transition, every refused pair and every invariant the aggregate can enforce. | ConnectSoft.AI.SoftwareFactory.ArtifactService |
AIFACTORY-TASK-056 Persistence in artifact-sql: migrations and mappings of VersionChains, Artifacts and LineageEdges |
migration | Migrations and mappings of the tables VersionChains, Artifacts and LineageEdges of the model with the columns of the twenty fields of AIFACTORY-TASK-055, the foreign keys, the unique indexes UX_Chains_Project_Name on TenantId, ProjectId and Name and UX_Artifacts_Chain_Version and the indexes IX_Artifacts_Tenant_Hash, IX_Artifacts_ProducerRun and IX_Lineage_Input; ProjectId is nullable in Artifacts and in VersionChains and empty for a tenant-level artifact and its chain (D125); the columns Passed, FinalOutput, PendingRemoval and Closed and the tables ArtifactReferences and ExportRequests are created by the migrations of AIFACTORY-TASK-3162, AIFACTORY-TASK-3166, AIFACTORY-TASK-3188, AIFACTORY-TASK-3971 and AIFACTORY-TASK-3176; every mapping carries the tenant row filter of the Factory profile and no column holds content; mapping tests run against an isolated test database, never a shared one. | ConnectSoft.AI.SoftwareFactory.ArtifactService |
AIFACTORY-TASK-3152 Verify the scaffold, the aggregate and the store of ArtifactService |
verification | Run dotnet build -c Release and dotnet test -c Release --filter "Category=Unit\|Category=Mapping" in the pipeline of the repository; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-781: the unchanged scaffold with the Factory profile, the six transitions and the refused pairs of the aggregate, the three tables with their unique indexes, the empty ProjectId of a tenant-level artifact and of its chain, the two tenant-level chains of one tenant with the same name refused and those of two tenants accepted, the tenant row filter against an isolated database, and the absence of a content column. |
ConnectSoft.AI.SoftwareFactory.ArtifactService |
AIFACTORY-US-782: ArtifactService host: five REST routes and three gRPC methods behind scope policies, messaging with the five events of the model and the audit evidence event, and two hosted workers¶
enabling
This PBI hosts the surface of the service and delivers the behaviour of no operation. The service descriptor file of the repository lists the eight operations as the model does. The REST operations are GetArtifact, PreviewArtifact and ListArtifactVersions under the scope factory.artifacts.read, ListRunArtifacts under factory.runs.read and ExportArtifacts under factory.artifacts.admin, of class external and idempotent on the Idempotency-Key header. The internal gRPC methods of the service Artifacts are Store (client streaming, shared-write), Fetch (server streaming, read) and RecordValidation (no streaming, shared-write). The contract test of the profile compares the hosted endpoints with that file in both directions. Each REST route sits behind the policy of its scope: a call without a token is answered 401, a valid user token without the scope or without a role in the project the request addresses is answered 403, and the audience a user token must carry is the one of the Knowledge gateway that fronts the service and that feature knowledge-host delivers in this increment (D125), because a user token has one audience and a gateway forwards it unchanged (ADR-0015). A workload token carries service scopes and never satisfies a REST scope policy. Each gRPC method requires a workload token that holds the service scope naming ArtifactService: a call without a workload identity is refused with UNAUTHENTICATED and a token without that scope with PERMISSION_DENIED, and the tenant and the project a workload forwards are read only under that scope. The answers that the model does not list for an operation, 401 for a missing token, 400 for an ExportArtifacts call without its key header and 503 while a required dependency does not answer, are given by the host and are reported to the owner as codes the model omits. The OpenAPI document and the proto fix the messages. artifact-v1 is the metadata message of Store, Fetch and GetArtifact, and ack-v1 is the reply of RecordValidation. The published schema docs/reference/schemas/artifact.schema.json follows the aggregate of the model (D125). projectId and the producer are optional, kind holds the eleven values of ArtifactKind, the chain is stated as chainId and versionInChain, accessScope, state, passed and validationRef are members, and contentHash has the pattern of the prefix sha256: followed by sixty-four lowercase hexadecimal characters. Golden files fix the messages, and the contract test compares the eighteen members the schema and the aggregate share by name, artifactId, tenantId, projectId, kind, name, mediaType, contentHash, contentRef, sizeBytes, classification, accessScope, descriptor, chainId, versionInChain, state, passed, validationRef and createdAt, and the required member validation with its status, which the message reads from passed as AIFACTORY-US-786 states. The list of members the two sides do not share is short and the test holds it completely. The schema states the producer as the optional object producedBy with runId, attemptId and agentId, which the message fills from producerRunId, producerAttemptId and producerAgentId, and with stepId and releaseId, which have no counterpart on the aggregate and stay absent. The schema states lineage as sources with sourceId, revision and chunkIds, the aggregate as lineage edges with input kind, input reference and relation. Only the schema has retention and, inside validation, checks and unverifiedClaims, which the message leaves absent. Only the aggregate has finalOutput and pendingRemoval, which the metadata message cannot carry because the schema allows no additional property. The names of the producer members, the verdict that the schema states as passed and again as validation.status, and the two fields outside the schema are reported to the owner as remaining differences and are not decided here. The messaging profile of the service is named artifact. The outbox writer enlists in the unit of work of a command, a handler or a worker step, so that a state change and its event commit together. The profile requires declared routing: every message the service publishes is listed under PublishedEvents of the OrleansMessaging section with a subscription or an unrouted reason, the start fails otherwise and an undeclared publish is refused. The section therefore declares six entries. Five are the events of the model with their topics, ArtifactStored, ArtifactValidated, ArtifactSuperseded, ArtifactDeleted and ProjectDataOffboarded, each with its route, in the run event envelope of the pinned contracts package (ADR-0014). The sixth is the audit evidence event AuditEvidenceSubmitted on audit.evidence.v1.evidence-submitted, declared with the event type and the topic constant of the pinned contracts package and its route to AuditService, because the deletion and the export write an audit-evidence-v1 record to the outbox of this service in the transaction of their command (AIFACTORY-US-789, AIFACTORY-US-790). The service publishes no message to itself: a recorded export request reaches ExportWorker as a row of the table ExportRequests and through no message (D125). The inbox registers five consumed events of other services, each handler deduplicated on the event id: RunCompleted of RunControlService for SealRunArtifacts and for RecordRunEnd, RunFailed and RunCancelled of RunControlService for RecordRunEnd, ProjectStateChanged of ProjectService for ExportOrDeleteOnClosing and ClassificationChanged of AuditService for ApplyClassification. It also subscribes to audit.evidence.v1.evidence-submitted, the topic on which every service delivers its audit evidence in the run event envelope, for the command RecordEvidenceReference of the model, deduplicated on the evidence id; the service receives its own evidence records on that topic like those of every other service (D125). The three events of RetentionResidencyService are not subscribed. Two workers are hosted with the retry policies, idempotency keys and concurrency of the model: RetentionSweeper on the schedule 0 4 * * * with a fixed retry of three attempts, the key artifactId and at most two in parallel partitioned by tenant, and ExportWorker with an exponential retry of five attempts, the key of project and export request and one at a time per tenant. The model gives ExportWorker two triggers: ProjectStateChanged of ProjectService, and a recorded export request, a row of ExportRequests in the state requested, which no event announces (D125). In this delivery ProjectStateChanged reaches the worker through the handler ExportOrDeleteOnClosing, which records the work of a closing project as such a row, so the worker has one input for a requested export and for a closing project alike: it picks up the rows in the state requested, which it reads per tenant through the index IX_ExportRequests_Tenant_State. How often the worker looks for recorded requests is a configuration value the model does not list. What each handler and worker does is delivered by AIFACTORY-US-787 to AIFACTORY-US-790 and by AIFACTORY-US-986. The options Knowledge:Artifacts:MaxArtifactMb, Knowledge:Artifacts:PreviewRenderers and Knowledge:Artifacts:DefaultRetentionDays, all three reloadable, and OrleansMessaging:ServiceName are bound from configuration.
Acceptance criteria
| AC1 | Given the service descriptor file and the hosted surface, when the contract test of the profile runs, then exactly the routes of ArtifactService/GetArtifact, ArtifactService/PreviewArtifact, ArtifactService/ListArtifactVersions, ArtifactService/ListRunArtifacts and ArtifactService/ExportArtifacts and the methods ArtifactService/Artifacts.Store, ArtifactService/Artifacts.Fetch and ArtifactService/Artifacts.RecordValidation are hosted with the scope, the side-effect class and the idempotency rule of model/services/knowledge/ArtifactService.yaml, and the test fails on an endpoint the file does not name and on an operation without an endpoint. |
| AC2 | Given each REST route called without a token, with a valid user token that lacks the scope of the route and with a user token of another audience, and each gRPC method called without a workload identity and with a workload token that lacks the service scope, when the call arrives, then it is answered 401, 403, 401, UNAUTHENTICATED and PERMISSION_DENIED respectively before any handler runs, and nothing is read or written (ADR-0015). |
| AC3 | Given a command that changes an ArtifactService/Artifact and is rolled back and one that commits, when the outbox of the artifact messaging profile is read, then the first left no record and the second left its record in the transaction of the change, the dispatcher publishes it in the run event envelope on the topic the model names for the event; the OrleansMessaging section declares the five events of the model and the audit evidence event AuditEvidenceSubmitted on audit.evidence.v1.evidence-submitted with its route to AuditService, six entries and no message the service publishes to itself; an audit-evidence-v1 record written through the sink of the audit library in the transaction of a command leaves the outbox on that topic; and a publish of a message the section does not declare is refused (ADR-0014, ADR-0012). |
| AC4 | Given fixture publishers of the five subscribed events and of the audit evidence event built from the pinned contracts package, when the same event id or the same evidence id is delivered twice, a recorded export request in the state requested is found by two looks of ExportWorker, or the schedule of RetentionSweeper fires twice under one idempotency key, then each handler or the worker runs once, RunCompleted reaches both SealRunArtifacts and RecordRunEnd, a handler that keeps failing is retried with backoff and never applied twice, and an event of RetentionResidencyService reaches no handler (model/services/knowledge/ArtifactService.yaml). |
| AC5 | Given the golden files of the proto and of the OpenAPI document, when the contract test compares the metadata message with docs/reference/schemas/artifact.schema.json, then the eighteen shared members artifactId, tenantId, projectId, kind, name, mediaType, contentHash, contentRef, sizeBytes, classification, accessScope, descriptor, chainId, versionInChain, state, passed, validationRef and createdAt and the member validation with its status are equal in name and type, kind holds the eleven values of ArtifactKind, contentHash matches the pattern of the schema, a message without projectId and without producedBy is valid, the test lists every member the schema and the aggregate do not share, that is producedBy against the three producer members, sources against the lineage edges, retention, checks and unverifiedClaims, which only the schema has, and finalOutput and pendingRemoval, which only the aggregate has, and a change of either side fails it. |
| Traces: services | ArtifactService |
| Traces: aggregates | ArtifactService/Artifact |
| Traces: apis | ArtifactService/GetArtifact, ArtifactService/PreviewArtifact, ArtifactService/ListArtifactVersions, ArtifactService/ListRunArtifacts, ArtifactService/ExportArtifacts, ArtifactService/Artifacts.Store, ArtifactService/Artifacts.Fetch, ArtifactService/Artifacts.RecordValidation |
| Traces: events | ArtifactService/ArtifactStored, ArtifactService/ArtifactValidated, ArtifactService/ArtifactSuperseded, ArtifactService/ArtifactDeleted, ArtifactService/ProjectDataOffboarded |
| Traces: descriptors | artifact-v1, ack-v1, audit-evidence-v1, run-event-envelope-v1 |
| Traces: adrs | ADR-0012, ADR-0014, ADR-0015, ADR-0028 |
| Depends on | AIFACTORY-US-781, feature:component-base-template-factory-profile, feature:contracts-package, feature:component-audit-factory-evidence |
| Sources | model/services/knowledge/ArtifactService.yaml, docs/reference/schemas/artifact.schema.json, docs/planes/knowledge-memory/services/artifact-service/index.md#apis, docs/planes/knowledge-memory/services/artifact-service/index.md#messages, docs/planes/knowledge-memory/services/artifact-service/index.md#workers-and-jobs |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-057 Contract and hosting of the surface: service descriptor, OpenAPI document and proto of the 5 REST and 3 gRPC operations behind their scope policies |
contract | The service descriptor file lists GetArtifact, PreviewArtifact, ListArtifactVersions, ListRunArtifacts, ExportArtifacts and Artifacts.Store, Artifacts.Fetch and Artifacts.RecordValidation with scope, side-effect class, idempotency and response codes as model/services/knowledge/ArtifactService.yaml does; the five routes are hosted behind the policies of factory.artifacts.read, factory.runs.read and factory.artifacts.admin with problem responses, the Idempotency-Key filter of ExportArtifacts and the audience of the Knowledge gateway for user tokens; the three methods are hosted behind the workload policy of the service scope; ListRunArtifacts is described with the codes 200 and 403 of the model and no 404 (D125); the OpenAPI document and the proto fix artifact-v1 and ack-v1 by golden files, which hold the text form of contentHash that the pattern of the schema fixes (the prefix sha256: and sixty-four lowercase hexadecimal characters), a message without projectId and without producedBy for a tenant-level artifact stored outside a run, and the member validation with its status (unvalidated, valid, invalid) beside passed and validationRef; the contract test compares the eighteen shared members and validation.status with docs/reference/schemas/artifact.schema.json, which follows the aggregate (D125), and lists every member the schema and the aggregate do not share: producedBy with runId, attemptId and agentId against producerRunId, producerAttemptId and producerAgentId, with stepId and releaseId that have no counterpart; sources against the lineage edges; retention and the members checks and unverifiedClaims of validation, which only the schema has; and finalOutput and pendingRemoval, which only the aggregate has; the behaviour of each operation is delivered by AIFACTORY-US-784 to AIFACTORY-US-790, not here. | ConnectSoft.AI.SoftwareFactory.ArtifactService |
AIFACTORY-TASK-058 Messaging skeleton: outbox and inbox wiring of the artifact profile for the 5 events of the model, the audit evidence event as published and as received, and 5 consumed events |
implementation | The outbox writer enlists in the unit of work of a command, a handler and a worker step, and the dispatcher of the artifact messaging profile publishes ArtifactStored, ArtifactValidated, ArtifactSuperseded, ArtifactDeleted and ProjectDataOffboarded in the run event envelope of the pinned contracts package, each declared with its topic and route under PublishedEvents of the OrleansMessaging section; the section declares a sixth published event, AuditEvidenceSubmitted on audit.evidence.v1.evidence-submitted, with the event type and the topic constant of the pinned contracts package and its route to AuditService, so that the sink of the pinned audit library writes audit-evidence-v1 records to the outbox of the service without an undeclared publish; the section declares these six entries and no message the service publishes to itself, because a recorded export request reaches ExportWorker as a row of ExportRequests (D125); the inbox registers RunCompleted of RunControlService for the two handlers SealRunArtifacts and RecordRunEnd, RunFailed and RunCancelled of RunControlService for RecordRunEnd, ProjectStateChanged of ProjectService and ClassificationChanged of AuditService, each handler deduplicated on the event id, and a subscription to audit.evidence.v1.evidence-submitted for the command RecordEvidenceReference, deduplicated on the evidence id; RetentionRuleChanged, DeletionOrderIssued and LegalHoldChanged of RetentionResidencyService are not subscribed, the handler of DeletionOrderIssued being built in I4 with that service; what each handler does is delivered by AIFACTORY-US-787, AIFACTORY-US-788, AIFACTORY-US-790 and AIFACTORY-US-986. | ConnectSoft.AI.SoftwareFactory.ArtifactService |
AIFACTORY-TASK-059 Worker hosting skeleton: schedule, trigger, retry policy and partitioning of RetentionSweeper and ExportWorker |
implementation | RetentionSweeper is hosted on the schedule 0 4 * * * with a fixed retry of three attempts, the idempotency key artifactId and at most two parallel executions partitioned by tenant; ExportWorker is hosted on the recorded export requests of the model (D125): it picks up the rows of ExportRequests in the state requested, which it reads per tenant through the index IX_ExportRequests_Tenant_State at an interval set by a configuration value the model does not list, with an exponential retry of five attempts, the idempotency key of project and export request and one execution at a time per tenant; the trigger ProjectStateChanged of the model reaches the worker through the handler ExportOrDeleteOnClosing, which records the work of a closing project as such a row; a duplicate trigger and a request found by two looks of the worker have no second effect; the option Knowledge:Artifacts:DefaultRetentionDays is bound, reloadable, for RetentionSweeper; what each worker does is delivered by AIFACTORY-US-789 and AIFACTORY-US-790. | ConnectSoft.AI.SoftwareFactory.ArtifactService |
AIFACTORY-TASK-3153 Verify the hosted surface, the messaging profile and the hosted workers of ArtifactService |
verification | Run dotnet build -c Release and dotnet test -c Release --filter "Category=Acceptance&Feature=HostingSurface"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-782: the surface compared with the service descriptor in both directions, the 401, 403, UNAUTHENTICATED and PERMISSION_DENIED answers of every operation, the outbox record committed and rolled back with its change, the six declared entries of the OrleansMessaging section with the audit evidence event among them and no message the service publishes to itself, an evidence record that leaves the outbox on audit.evidence.v1.evidence-submitted, the refused undeclared publish, the deduplicated inbox under fixture publishers of the five subscribed events and of the audit evidence event, RunCompleted delivered to both of its handlers, the duplicate worker trigger and the recorded export request found by two looks of ExportWorker, and the golden files compared with docs/reference/schemas/artifact.schema.json with the eighteen shared members and the complete list of members the schema and the aggregate do not share. |
ConnectSoft.AI.SoftwareFactory.ArtifactService |
AIFACTORY-US-783: ArtifactService filters every query by tenant, answers a foreign artifact as not found, starts only with its secret references and keeps content out of telemetry¶
enabling
ArtifactService holds the content of every tenant, and the model classifies its data as confidential, so isolation and the silence of its telemetry are deliverables of their own. Tenant isolation is the row filter of the profile: every query on the five tables of artifact-sql, VersionChains, Artifacts, LineageEdges, ArtifactReferences and ExportRequests, carries the tenant of the trusted scope, so an artifact, a chain, a lineage edge, a reference record or an export request of another tenant is invisible, with the one read admission for the platform tenant that is stated below. A request that addresses one by identifier or by content reference is answered 404, over gRPC the status NOT_FOUND, the same answer as for an identifier that does not exist, and nothing in the answer confirms that it exists (ADR-0015). Content is held in artifact-blob per tenant and hash: equal content of two tenants is two blobs, and a content reference of one tenant never resolves under another; deduplication across tenants is a later capability on the service page and is not built. Inside a tenant the project is the second boundary. A user token reaches an artifact only when it holds a role in the project of the artifact or the tenant-wide Platform admin role, and a workload only when the project it forwards is the project of the artifact; another project of the same tenant is answered 403, over gRPC PERMISSION_DENIED, because a missing right inside the own tenant is never answered as not found. The aggregate carries accessScope, which says who may read beyond the project, and the model types it as json without a grammar. This delivery stores the value as given and returns it, and evaluates no value: until the owner defines the grammar nobody is admitted beyond the project of an artifact, which fails closed. Two further rules are decided (D125) and stand as invariants of the model. The first is the tenant-level artifact. The project of an artifact is optional, and an artifact without a project belongs to its tenant: a workload that forwards a tenant and no project stores a tenant-level artifact, whose projectId is absent on the aggregate, in the tables Artifacts and VersionChains, in the payload of ArtifactStored and in artifact-v1 (AIFACTORY-US-784). AgentRegistryService stores the manifests and the authoring documents of its seeded releases in this way for the platform tenant. A tenant-level artifact stands outside the project boundary: every workload of its tenant reads it whatever project it forwards. Over REST no project role can name it, so a user token reads it only with the tenant-wide Platform admin role of its tenant and is answered 403 otherwise. The second rule is the read admission of the platform tenant: tenant-level artifacts of the platform tenant are read by every tenant through the internal Artifacts.Fetch only, no REST read admits a token of another tenant, and every write stays in the tenant of the caller. The runtime and ModelRouterService read the documents of the seeded releases while they work under the tenant of a customer, so the row filter of Artifacts, VersionChains and LineageEdges admits, for reading, the tenant-level artifacts of the platform tenant under the scope of every tenant, as the filter of ModelProfiles in ModelRouterService admits the profiles of the platform tenant. Which tenant is the platform tenant is a value of the Factory profile configuration and never a member of a request. The admission covers the workload read Artifacts.Fetch by identifier or by content reference and nothing else. An artifact that belongs to a project of the platform tenant stays invisible to every other tenant and is answered NOT_FOUND, and over REST a token of another tenant is answered 404 for every artifact of the platform tenant. Every write stays in the forwarded tenant: a store, a verdict, a relabel, a deletion and an export never touch a row of another tenant, the platform tenant included, so a workload of a customer tenant that stores under the name of a platform document creates an artifact of its own tenant and changes nothing of the platform tenant. The two secrets of the model, artifact-blob and messaging-transport, reach the service as secret references of the key vault; no secret value is in the repository, in configuration or in telemetry, and the service is unready while a reference cannot be resolved. Telemetry follows the Factory conventions through the single enrichment registration of the pinned observability libraries. The three instruments of the model are created through the instrument helper: connectsoft.factory.artifacts.stored with the dimensions tenant and kind, connectsoft.factory.artifacts.bytes with tenant, and connectsoft.factory.artifacts.deleted with tenant and reason, each with tenant and project by default. Activities and log records carry tenant and project, and run, step and attempt when the scope of the call carries a run. No content of an artifact, no preview text and no export content reaches a metric, an activity or a log record: the hash, the size, the artifact identifier and the reference stand in its place (ADR-0019). connectsoft.factory.artifacts.bytes is the source of the storage meter. The model lists CostUsageService as an optional dependency for the StorageGb meter, but the one recording method of that service, Usage.RecordUsage, records usage from a model or tool receipt and the model names no method for a stored quantity, so no call is made and the gap is reported to the owner. Readiness is unready until artifact-sql is migrated, artifact-blob answers, the outbox check of the profile is healthy and the identity authority is reachable; an outage of PolicyEngineService fails the calls that need a decision (AIFACTORY-US-784, AIFACTORY-US-788 and AIFACTORY-US-790) and is not a readiness condition.
Acceptance criteria
| AC1 | Given artifacts of two tenants, when a caller of the first tenant addresses an artifact of the second by identifier through ArtifactService/GetArtifact or by identifier or content reference through ArtifactService/Artifacts.Fetch, then the answer is 404 and NOT_FOUND respectively, byte for byte the answer for an identifier that does not exist, no list of the first tenant ever holds a row of the second, and equal content of the two tenants is held as two blobs; and given a tenant-level artifact and a project artifact of the platform tenant, when a workload of either tenant calls ArtifactService/Artifacts.Fetch, then the tenant-level artifact is delivered with its hash and the project artifact is answered NOT_FOUND, ArtifactService/GetArtifact answers 404 for both to a token of another tenant, and no write of either tenant changes a row of the platform tenant (ADR-0015). |
| AC2 | Given an ArtifactService/Artifact of one project and a caller of the same tenant whose token grants, or whose workload forwards, another project only, when the artifact is read, then the answer is 403 over REST and PERMISSION_DENIED over gRPC, and an accessScope value stored with the artifact is returned as given and admits nobody beyond the project in this delivery; a tenant-level artifact of the tenant is read by a workload that forwards any project of the tenant or none, and over REST only by a token with the tenant-wide Platform admin role (model/services/knowledge/ArtifactService.yaml). |
| AC3 | Given a start without a resolvable secret reference for artifact-blob or for messaging-transport, when readiness is probed, then the service is unready and names the missing reference, and neither the configuration of the repository nor any log record holds a secret value (model/services/knowledge/ArtifactService.yaml). |
| AC4 | Given fixture documents that carry a marker text and a run that stores, fetches, previews, exports and deletes them, when the collected metrics, activities and log records are scanned, then none holds the marker or any other content, the metrics carry tenant and project beside their modelled dimensions, and the activities and log records of a call made under the scope of a run carry run, step and attempt (ADR-0019). |
| AC5 | Given content of a known size stored for a tenant and later deleted, when connectsoft.factory.artifacts.bytes is read, then it rose and fell by that size for the tenant, and the recording fake of CostUsageService received no call, because the model names no method for a stored quantity (model/services/knowledge/ArtifactService.yaml). |
| Traces: services | ArtifactService |
| Traces: aggregates | ArtifactService/Artifact |
| Traces: apis | ArtifactService/GetArtifact, ArtifactService/Artifacts.Fetch |
| Traces: adrs | ADR-0015, ADR-0019 |
| Traces: requirements | NFR-03 |
| Relates: nfrs | NFR-03 |
| Depends on | AIFACTORY-US-781, AIFACTORY-US-782, feature:component-base-template-factory-profile, feature:component-observability-factory-conventions |
| Sources | model/services/knowledge/ArtifactService.yaml, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/architecture/data-governance.md#logging-and-telemetry, docs/planes/knowledge-memory/services/artifact-service/index.md#security, docs/planes/knowledge-memory/services/artifact-service/index.md#metrics-and-observability |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-060 Security, tenancy and telemetry of ArtifactService |
implementation | Every query of the tables of artifact-sql runs under the tenant row filter of the Factory profile, so an artifact of another tenant is answered 404 and NOT_FOUND exactly as an unknown one; the blob path is formed from tenant and hash; another project of the same tenant is answered 403 and PERMISSION_DENIED; a tenant-level artifact, stored by a workload that forwards no project and held without a projectId (D125), is read by every workload of its tenant and over REST only by a token with the tenant-wide Platform admin role; the read filter of the three mappings admits the tenant-level artifacts of the platform tenant, named by the configuration of the Factory profile, for Artifacts.Fetch under the scope of every tenant, as the filter of ModelProfiles in ModelRouterService does, admits no project artifact of the platform tenant and no REST read of another tenant, and every write stays in the forwarded tenant; accessScope is stored and returned as given and evaluated for nobody; artifact-blob and messaging-transport are read as secret references and a missing reference keeps the service unready; the instruments connectsoft.factory.artifacts.stored, connectsoft.factory.artifacts.bytes and connectsoft.factory.artifacts.deleted are created through the instrument helper with their modelled dimensions; no content reaches a metric, an activity or a log record; no call to CostUsageService is made. | ConnectSoft.AI.SoftwareFactory.ArtifactService |
AIFACTORY-TASK-3154 Two-tenant fixture with user and workload tokens, marker documents and a telemetry collector |
fixture | The acceptance suite holds two tenants with two projects each and a third tenant configured as the platform tenant with one project, user tokens of the gateway audience with and without each scope and project role and with the tenant-wide Platform admin role, workload tokens with and without the service scope naming ArtifactService, workloads that forward a tenant with a project and without one, a tenant-level artifact and a project artifact of the platform tenant and a tenant-level artifact of each other tenant, documents of several kinds and media types that carry a marker text, an in-memory collector of metrics, activities and log records, and a recording fake of CostUsageService; the fixture serves the suites of AIFACTORY-US-783 to AIFACTORY-US-790. | ConnectSoft.AI.SoftwareFactory.ArtifactService |
AIFACTORY-TASK-3155 Verify tenancy, secret references and telemetry of ArtifactService |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Feature=TenancyAndTelemetry"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-783: 404 and NOT_FOUND for a foreign artifact equal to the answer for an unknown one, the tenant-level artifact of the platform tenant fetched by a workload of every tenant while its project artifact and every REST read of another tenant are refused as not found, the writes that never change a row of the platform tenant, 403 and PERMISSION_DENIED for another project of the tenant, the tenant-level artifact read by every workload of its tenant and over REST by the Platform admin role only, the unready start without a secret reference, the telemetry scan for the marker text, and the rise and fall of connectsoft.factory.artifacts.bytes with no call to CostUsageService. |
ConnectSoft.AI.SoftwareFactory.ArtifactService |
AIFACTORY-US-784: Store content once by hash with its producer, lineage and version chain, announce it and supersede the earlier version¶
behavior
A workload stores content through the internal gRPC method Artifacts.Store, a client stream of class shared-write. The callers are the services the model lists with a dependency on ArtifactService; in this increment RunControlService stores the resolved execution snapshot of a run, WorkflowEngineService the task contract of a step and the readiness bundle, AgentRegistryService its manifests and authoring documents, BlueprintService and GenerationRecipeService their documents and reports, ModelRouterService and ToolAdapterService outputs, results and receipts, and AgentRuntimeService checkpoints and produced artifacts. The caller presents a workload token that holds the service scope naming ArtifactService and forwards the tenant and the project of its work; the tenant and the project of the artifact are those of that trusted scope and never members of the request (ADR-0015). A workload that forwards a tenant and no project stores a tenant-level artifact; AgentRegistryService does so for the platform tenant, whose seeded releases belong to no project. Such an artifact has no project (D125): projectId is absent on the aggregate and in its artifact-v1, the ProjectId of its row in Artifacts and of its chain in VersionChains is empty, and the payload of its ArtifactStored carries no projectId. Its version chain is found by tenant and name, and the unique index UX_Chains_Project_Name on TenantId, ProjectId and Name keeps the tenant-level chains of two tenants with the same name apart. No value stands in for the missing project. Who reads a tenant-level artifact is stated by AIFACTORY-US-783, and a tenant-level artifact is no candidate of the retention sweep (AIFACTORY-US-789). The first message of the stream is the metadata: name, kind, media type, classification, access scope, the optional descriptor id of a typed body, the optional producer (run, attempt, agent), the optional content hash the caller computed, and the lineage edges to what the content derived from, each with an input kind (artifact, chunk, context-snapshot, receipt or run-input), an input reference and a relation (derived-from, generated-from, validated-by or summarises). The following messages carry the content, and the service hashes the bytes it receives. contentHash is the SHA-256 digest of those bytes, written as the prefix sha256: followed by sixty-four lowercase hexadecimal characters. The service and its callers share this one form: artifact-v1 fixes it by the pattern of the member (D125), and the golden files of AIFACTORY-US-782 hold it. Nothing is written when the request is invalid: a kind outside ArtifactKind, a lineage edge whose input kind or relation the model does not list, a producer attempt or agent without its run, a missing name, media type or classification, a stated hash that is not of that form or differs from the hash of the received content, and content above Knowledge:Artifacts:MaxArtifactMb are each refused with INVALID_ARGUMENT. The service then has the store decided through Policy.Decide of PolicyEngineService, the required, fail-fast dependency the model lists for classification and redaction on store and preview. The request is a policy-decision-v1 with the subject of the trusted scope, that is the workload as caller of the kind workload, the tenant and, when one is forwarded, the project, and with the action members kind, target, sideEffectClass and classification. The action kind is store, the value policy-decision-v1 lists for the store of an artifact (D125), with the target artifact-store, the side-effect class shared-write and the classification of the metadata. Every outcome of the schema is mapped. The outcome allow stores. The outcomes deny and allow-with-approval refuse the store with PERMISSION_DENIED and the decision id in the status detail, because the service never grants, opens or assumes an approval. The outcome allow-with-constraints is refused in the same way: content is immutable and addressed by its hash, so the service can apply no constraint to it, and storing it unconstrained would ignore the decision. When PolicyEngineService does not answer, the call fails with UNAVAILABLE. One more point of that dependency is reported to the owner: the model of AuditService lists ArtifactService as a caller of its classification methods while the model of ArtifactService names PolicyEngineService alone, which this PBI follows. The content is written to artifact-blob once per tenant and hash. Then, in one transaction, the version chain of the tenant, the project where one is forwarded, and the name of the request is found or created in VersionChains, the Artifact is written in state Stored with the next versionInChain, LatestVersion is raised, the lineage edges are written, and the ArtifactStored outbox record is written with artifactId, tenantId, the projectId of a project artifact, kind, contentHash, the optional producerRunId, chainId, versionInChain and the optional descriptor. When the metadata names a producer run, the same transaction writes the reference record of that run, which AIFACTORY-US-986 delivers. When the chain held an earlier latest version in state Stored or Validated, that artifact moves to Superseded through NewVersionStored in the same transaction and ArtifactSuperseded is written with its artifactId, tenantId, chainId and the newArtifactId; an earlier version that is Deleted stays Deleted and is not announced. The reply is the artifact-v1 of the stored artifact with artifactId, contentHash and contentRef. The method is idempotent on tenant and hash within a chain, and the rule regards the state of what it finds. The idempotent answer applies to an artifact of that tenant, hash and chain that still holds content: a repeat returns that artifact and writes no row, no blob and no event, so a caller that lost the answer repeats the call, and ArtifactService itself never repeats a write on behalf of a caller. That holds for a Superseded version as well: when a chain received content A, then B, then A again, the third store returns the Superseded artifact of A unchanged, the latest version stays B and nothing is announced. D125 records this reading: a store that repeats the content of a superseded version returns that version and appends none. A hash that matches only a Deleted artifact of the chain is no repeat, because that artifact has no content and Artifacts.Fetch refuses it: the content is written as a new artifact with the next versionInChain, its blob is written again and ArtifactStored announces it, so no caller is told that content is stored which is not. The same content stored under another name or project of the tenant is a new artifact in that chain that references the same blob. Two concurrent stores of different content into one chain receive distinct consecutive versions, which the unique index UX_Artifacts_Chain_Version guarantees. A store and the removal of content after a deletion (AIFACTORY-US-789) exclude each other per tenant and hash through one lock in artifact-sql: the removal runs only under that lock, after it has checked again that no artifact of the tenant holds the content, and the transaction of a store takes the same lock and verifies through the content port that the blob is present before it commits. A store that finds the blob gone commits nothing and fails with UNAVAILABLE, and its repeat writes the blob again, so a Stored artifact never exists without content. The failure modes are covered. When artifact-blob is unavailable the call fails with UNAVAILABLE and nothing is committed, so callers fail fast; an attempt cannot checkpoint without the store. When artifact-sql fails after the blob was written, the call fails with UNAVAILABLE, no row and no outbox record exists, and the blob stays under tenant and hash, where the repeat finds and reuses it. A blob that no repeat ever claims is referenced by no artifact, is counted by no instrument and is reachable by no reference; that nothing removes such a blob is reported to the owner. When content arrives whose hash equals that of held content of the tenant while its size differs, a hash collision is suspected: the store is refused with an explicit error that names it, over gRPC the status FAILED_PRECONDITION, nothing is written and the refusal is logged for the incident investigation. connectsoft.factory.artifacts.stored counts each new artifact by tenant and kind, and connectsoft.factory.artifacts.bytes rises by the size of content the tenant did not hold yet. The callers keep a reference and a hash; the model does not say whether that reference is artifactId or contentRef, so the reply carries both and Artifacts.Fetch accepts both (AIFACTORY-US-785), and the point is reported to the owner.
Acceptance criteria
| AC1 | Given a workload token that holds the service scope, a forwarded tenant and project, and a stream with valid metadata, a lineage edge of kind run-input and content, when ArtifactService/Artifacts.Store completes, then artifact-blob holds the content once under tenant and hash, one ArtifactService/Artifact exists in state Stored as version 1 of the chain of that project and name with the producer and the lineage edge as given, the reply is artifact-v1 with artifactId, contentHash and contentRef, and the ArtifactService/ArtifactStored outbox record was written in the same transaction, with contentHash as sha256: and sixty-four lowercase hexadecimal characters; and given a workload that forwards the platform tenant and no project, when it stores a release manifest, then the artifact is a tenant-level artifact without a projectId, its chain in VersionChains has an empty ProjectId and is found by tenant and name, its ArtifactService/ArtifactStored carries no projectId, the same name stored without a project by a workload of another tenant is a chain of that tenant and no violation of UX_Chains_Project_Name, and a workload of another tenant fetches the manifest of the platform tenant with the stated hash (SCN-ArtifactService-006, ADR-0014). |
| AC2 | Given that artifact, when the same content is stored again in the same chain, then the same artifact is returned and no row, blob or outbox record is added; when other content is stored under the same project and name, then a new artifact is written as version 2, the first moves from Stored, or from Validated, to Superseded through NewVersionStored, and ArtifactService/ArtifactSuperseded with artifactId, tenantId, chainId and newArtifactId is written in the same transaction as the ArtifactService/ArtifactStored of the new version; when the content of the Superseded version 1 is stored a third time, then that Superseded artifact is returned unchanged, the latest version stays 2 and nothing is announced; and when the hash of a store matches only a Deleted artifact of the chain, then a new artifact with the next versionInChain is written, its blob is written again and it is announced (SCN-ArtifactService-006, SCN-ArtifactService-011, XL-06). |
| AC3 | Given a caller without a workload identity, a token without the service scope, metadata with an unknown kind, an unlisted lineage relation or a stated hash that differs from the content, content above Knowledge:Artifacts:MaxArtifactMb, or a decision of PolicyEngineService/Policy.Decide with the outcome deny, allow-with-approval or allow-with-constraints, when ArtifactService/Artifacts.Store is called, then it is refused with UNAUTHENTICATED, PERMISSION_DENIED, INVALID_ARGUMENT, INVALID_ARGUMENT and PERMISSION_DENIED respectively, a refusal after a decision carries the decision id, no blob, row or outbox record remains, only the outcome allow stores, and the request the policy engine received was a policy-decision-v1 with the action kind store, the target artifact-store, the side-effect class shared-write and the classification of the metadata (SCN-ArtifactService-006, ADR-0015). |
| AC4 | Given artifact-blob or PolicyEngineService does not answer, when ArtifactService/Artifacts.Store is called, then the call fails with UNAVAILABLE, nothing is committed and a repeat after recovery stores the content once; given artifact-sql fails after the blob was written, then the call fails with UNAVAILABLE, no row or outbox record exists and the repeat reuses the blob; given the removal of the content of a deleted last holder runs while the same content is stored again, then the two exclude each other and no Stored artifact is left without content; and given held content of the tenant with the same hash and another size, then the store is refused with FAILED_PRECONDITION naming the suspected collision and nothing is written (SCN-ArtifactService-006, model/services/knowledge/ArtifactService.yaml). |
| AC5 | Given the outbox records of a store that superseded a version, when the dispatcher of the artifact messaging profile publishes ArtifactService/ArtifactStored on artifacts.artifacts.v1.artifact-stored and ArtifactService/ArtifactSuperseded on artifacts.artifacts.v1.artifact-superseded, then each is sent in the run event envelope with the payload members of the model and without content, and a transport outage is retried with backoff so that neither event is lost or duplicated under its event id (SCN-ArtifactService-009, SCN-ArtifactService-011, ADR-0012). |
| Traces: services | ArtifactService, PolicyEngineService |
| Traces: aggregates | ArtifactService/Artifact |
| Traces: apis | ArtifactService/Artifacts.Store, PolicyEngineService/Policy.Decide |
| Traces: events | ArtifactService/ArtifactStored, ArtifactService/ArtifactSuperseded |
| Traces: descriptors | artifact-v1, policy-decision-v1, run-event-envelope-v1 |
| Traces: adrs | ADR-0012, ADR-0014, ADR-0015, ADR-0019 |
| Traces: requirements | FR-08, XL-06 |
| Traces: scenarios | SCN-ArtifactService-006, SCN-ArtifactService-009, SCN-ArtifactService-011 |
| Relates: nfrs | NFR-05 |
| Depends on | AIFACTORY-US-781, AIFACTORY-US-782, AIFACTORY-US-783, feature:policy-engine-service |
| Sources | model/services/knowledge/ArtifactService.yaml, model/services/governance/PolicyEngineService.yaml, docs/reference/schemas/artifact.schema.json, docs/reference/schemas/policy-decision.schema.json, docs/planes/knowledge-memory/services/artifact-service/index.md#failure-and-recovery |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-3156 Content port over artifact-blob keyed by tenant and hash |
implementation | A content port with one binding to artifact-blob through the storage abstractions library the model lists: it writes a stream once under tenant and hash and reports whether the content was already held and with which size, tells whether a blob is present, reads a stream by tenant and hash, removes content, and issues a delegated, read-only reference of the blob store for one blob that is limited in time and carries no account credential; the held check of a store and the removal of content exclude each other per tenant and hash through one lock in artifact-sql, which the transaction of a store takes before it verifies that the blob is present and commits, and under which a removal checks again that no artifact of the tenant holds the content; the credential comes from the secret reference artifact-blob; an outage surfaces as an unavailable error of the port and never as a partial write that a reader could see. | ConnectSoft.AI.SoftwareFactory.ArtifactService |
AIFACTORY-TASK-3157 Artifacts.Store with validation, policy decision, version chain, supersession and the outbox records |
implementation | Artifacts.Store reads the metadata message and the content stream, hashes the content with SHA-256 and states contentHash as sha256: and sixty-four lowercase hexadecimal characters, refuses the invalid requests of AIFACTORY-US-784 with INVALID_ARGUMENT, and has the store decided through Policy.Decide with a policy-decision-v1 request whose action carries the kind store (D125), the target artifact-store, the side-effect class shared-write and the classification of the metadata: the outcome allow stores, and deny, allow-with-approval and allow-with-constraints are refused with PERMISSION_DENIED and the decision id; a workload that forwards a tenant and no project stores a tenant-level artifact without a projectId, with an empty ProjectId in Artifacts and in VersionChains and no projectId in the ArtifactStored payload (D125), and no value stands in for the missing project; the content is written through the content port, and in one transaction the service takes the lock of tenant and hash, verifies that the blob is present, finds or creates the chain of tenant, project where one is forwarded, and name, writes the artifact Stored with the next version and its lineage edges, applies NewVersionStored to an earlier latest version that is Stored or Validated, and writes ArtifactStored and, when a version was superseded, ArtifactSuperseded; a repeat with the same tenant, hash and chain returns the artifact that still holds content, a Superseded one unchanged and unannounced, while a hash that matches only a Deleted artifact of the chain is written as a new artifact with the next version and its blob is written again; an unavailable blob store or policy engine fails the call with UNAVAILABLE and commits nothing; a transaction that fails after the blob was written fails the call with UNAVAILABLE and leaves a blob the repeat reuses; a suspected hash collision is refused with FAILED_PRECONDITION; the reply is artifact-v1 with artifactId, contentHash and contentRef. | ConnectSoft.AI.SoftwareFactory.ArtifactService |
AIFACTORY-TASK-3158 Fakes of Policy.Decide and of the blob store, and builders of store streams |
fixture | The acceptance suite holds a fake of Policy.Decide that answers each of the four outcomes of policy-decision-v1 (allow, allow-with-approval, deny and allow-with-constraints) with a decision id, stops answering, and records the subject and the action members kind, target, sideEffectClass and classification of each request so that a test asserts them, a blob store double behind the content port that can be stopped, can lose an answer after a write, can be seeded with content of a given hash and another size and honours the clock of the suite for the lifetime of a reference, a switch that fails the transaction of artifact-sql after a blob write and one that holds a removal while a store of the same content runs, and builders of metadata messages and content streams for every ArtifactKind, with and without a forwarded project, including two streams sent concurrently into one chain. | ConnectSoft.AI.SoftwareFactory.ArtifactService |
AIFACTORY-TASK-3159 Verify store-content-by-hash-in-a-version-chain through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-ArtifactService-006\|Scenario=SCN-ArtifactService-009\|Scenario=SCN-ArtifactService-011)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-784: the first store with the fixed form of contentHash, the tenant-level store of a release manifest for the platform tenant without a project and its fetch by a workload of another tenant, the idempotent repeat, the new version with the superseded one from Stored and from Validated, a store whose hash equals a Superseded version of the chain and one whose hash equals only a Deleted artifact of the chain, two concurrent stores with distinct versions, every refusal, the four outcomes of the policy decision with the asserted request members, the unavailable blob store and policy engine, the transaction that fails after the blob write, the removal held against a store of the same content, the suspected collision, and the publication and payload of ArtifactStored and ArtifactSuperseded; consumer handling is proven by the suites of the consumers. |
ConnectSoft.AI.SoftwareFactory.ArtifactService |
AIFACTORY-US-785: Stream the content of an artifact to a workload of its tenant and project by artifact identifier or content reference¶
behavior
A workload reads content through the internal gRPC method Artifacts.Fetch, a server stream of class read. In this increment AgentRuntimeService reads the task contract and the resolved execution snapshot of an attempt by the references of the lease answer, WorkflowEngineService reads a memo a readiness member names, BlueprintService reads the document it validates, and ModelRouterService reads profile definitions and evaluation records; each presents a workload token that holds the service scope naming ArtifactService and forwards the tenant and the project of its work. The request names the artifact by its artifactId or by the contentRef the reply of Artifacts.Store returned. The first message of the stream is the artifact-v1 metadata of the artifact, the following messages carry the content in the order it was stored, and the stream then completes. The service changes nothing and writes no event; reading the same artifact twice yields the same messages. It does not hash the content again on a read: the caller compares the hash of what it read with the hash it kept, as the callers of the model do, and content is used only after its stream completed. A Stored, a Validated and a Superseded artifact are served alike, because a caller pins a version by its hash and a newer version does not take an older one away. A Deleted artifact has no content: the call is refused with FAILED_PRECONDITION and no message is streamed, while the metadata of such an artifact stays readable through GetArtifact (AIFACTORY-US-787). A contentRef can be held by several artifacts of the tenant, because content is stored once per tenant and hash and a chain of another name or project may reference it; a request by contentRef is served when the trusted scope admits at least one artifact that holds it and still has content, and the metadata message is the one of an admitted artifact. Two artifacts stand outside the project boundary, as AIFACTORY-US-783 states. A tenant-level artifact, stored by a workload that forwarded no project, is served to every workload of its tenant whatever project it forwards. And a tenant-level artifact of the platform tenant is served to a workload of every tenant, by identifier or by content reference: this is how AgentRuntimeService, WorkflowEngineService and ModelRouterService read the authoring documents of the seeded releases, which AgentRegistryService stored for the platform tenant, while they work under the tenant of a customer. A project artifact of the platform tenant is not admitted. Refusals: a call without a workload identity is refused with UNAUTHENTICATED, a token without the service scope with PERMISSION_DENIED, a request that names neither an identifier nor a reference with INVALID_ARGUMENT, an artifact of another project of the tenant with PERMISSION_DENIED, and an identifier or a reference that the tenant of the caller does not hold with NOT_FOUND, which is also the answer for an artifact of another tenant and never confirms that it exists; an attempt that receives NOT_FOUND takes the failure class permanent (ADR-0015). When artifact-blob or artifact-sql is unavailable before the first message the call fails with UNAVAILABLE; when the blob store fails during the stream, the stream ends with UNAVAILABLE without a completion, and the caller discards what it received and reads again. No content reaches telemetry: the activity of a fetch carries the artifact identifier, the hash and the size.
Acceptance criteria
| AC1 | Given an ArtifactService/Artifact stored through ArtifactService/Artifacts.Store and a workload of its tenant and project with the service scope, when ArtifactService/Artifacts.Fetch is called with its artifactId, then the stream delivers the artifact-v1 metadata message, then the content whose bytes equal the stored ones and whose hash equals contentHash, and completes; no row, blob or outbox record is written (SCN-ArtifactService-007). |
| AC2 | Given the same artifact, when it is fetched by its contentRef, then the same bytes are delivered; a Validated and a Superseded artifact are served like a Stored one; and a Deleted artifact is refused with FAILED_PRECONDITION without a message, because its content was removed and only its metadata and lineage remain (SCN-ArtifactService-007, model/services/knowledge/ArtifactService.yaml). |
| AC3 | Given a caller without a workload identity, a token without the service scope, a workload that forwards another project of the tenant, a request that names neither an identifier nor a reference, or an identifier the tenant of the caller does not hold, when ArtifactService/Artifacts.Fetch is called, then it is refused with UNAUTHENTICATED, PERMISSION_DENIED, PERMISSION_DENIED, INVALID_ARGUMENT and NOT_FOUND respectively, an artifact of another tenant is answered NOT_FOUND exactly as an unknown one, and no message is streamed (SCN-ArtifactService-007, ADR-0015). |
| AC4 | Given the blob store becomes unavailable after the metadata message was streamed, when the stream continues, then it ends with UNAVAILABLE without a completion, and a repeated ArtifactService/Artifacts.Fetch after recovery delivers the whole content from the metadata message on (SCN-ArtifactService-007). |
| AC5 | Given a tenant-level artifact of the platform tenant, a project artifact of the platform tenant and a tenant-level artifact of a customer tenant, when a workload of another customer tenant calls ArtifactService/Artifacts.Fetch for each, then the first is delivered with the bytes and the hash that were stored, by artifactId and by contentRef alike, and the other two are answered NOT_FOUND; and a workload of the customer tenant that forwards any of its projects reads the tenant-level artifact of its own tenant (SCN-ArtifactService-007, ADR-0015). |
| Traces: services | ArtifactService |
| Traces: aggregates | ArtifactService/Artifact |
| Traces: apis | ArtifactService/Artifacts.Fetch, ArtifactService/Artifacts.Store |
| Traces: descriptors | artifact-v1 |
| Traces: adrs | ADR-0015, ADR-0019 |
| Traces: requirements | FR-08 |
| Traces: scenarios | SCN-ArtifactService-007 |
| Depends on | AIFACTORY-US-783, AIFACTORY-US-784 |
| Sources | model/services/knowledge/ArtifactService.yaml, model/services/agent-mesh/AgentRuntimeService.yaml, docs/planes/knowledge-memory/services/artifact-service/index.md#apis |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-3160 Artifacts.Fetch server stream by artifact identifier or content reference |
implementation | Artifacts.Fetch resolves the artifact by artifactId or by contentRef among the artifacts of the forwarded tenant and the tenant-level artifacts of the platform tenant that the read filter of AIFACTORY-US-783 admits, admits the forwarded project and, whatever project is forwarded, a tenant-level artifact, streams the artifact-v1 metadata message and then the content from the content port, and completes; it serves Stored, Validated and Superseded artifacts, refuses a Deleted one with FAILED_PRECONDITION, answers UNAUTHENTICATED, PERMISSION_DENIED, INVALID_ARGUMENT and NOT_FOUND (also for an artifact of another tenant, ADR-0015) before the first message, ends with UNAVAILABLE when the blob store fails during the stream, and writes nothing. | ConnectSoft.AI.SoftwareFactory.ArtifactService |
AIFACTORY-TASK-3161 Verify fetch-artifact-content-by-reference through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-ArtifactService-007"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-785 over artifacts in every state, by identifier and by content reference, with the tenants, the platform tenant and the tenant-level artifacts of the fixture of AIFACTORY-TASK-3154 and a blob store stopped before and during the stream. |
ConnectSoft.AI.SoftwareFactory.ArtifactService |
AIFACTORY-US-786: Attach a validator verdict to a stored artifact and announce it¶
behavior
A workload attaches the verdict of a validator to an artifact through the internal gRPC method Artifacts.RecordValidation, of class shared-write and without streaming. The request names the artifact, the verdict passed and the validationRef, the reference of the record the validator produced. The artifact moves from Stored to Validated through the trigger ValidationRecorded, validationRef and the verdict passed are set, and ArtifactValidated with artifactId, tenantId, passed and validationRef is written to the outbox in the same transaction. Validated means that a validator recorded a verdict, passing or failing; it does not mean that the artifact passed. Where the verdict is kept and shown is defined by the model (D125). The aggregate keeps it in the field passed, the column Passed of Artifacts: true for a passed and false for a failed verdict, and absent while no verdict is recorded. artifact-v1, the descriptor the model names for the replies of Store, Fetch and GetArtifact, carries passed and validationRef as members and requires the member validation with a status, which is read from passed: the metadata of an artifact shows validation.status unvalidated before a verdict was recorded, valid for passed true and invalid for passed false, with the validationRef as the details reference of the recorded check; the value partial of the schema is never produced, because the method records one verdict. The migration of this PBI creates the column Passed. The reply is ack-v1, which states accepted or conflict. The method is idempotent on the artifact, the verdict and the reference: a repeat of the recorded verdict with the recorded reference is acknowledged as accepted and changes nothing in every state that still carries that validationRef, that is for a Validated artifact and equally for one that was superseded or deleted after its verdict, so a caller that lost the answer repeats the call whatever happened to the artifact since. The model has one transition into Validated, from Stored. A different verdict or reference for an artifact that carries a verdict, and any verdict for a Superseded or a Deleted artifact that carries none, is therefore answered with ack-v1 stating conflict; the state, the reference and the kept verdict stay as they are and no event is written. A verdict is recorded only in the tenant the caller forwards: a tenant-level artifact of the platform tenant, which another tenant may read, is answered NOT_FOUND here, because the admission of AIFACTORY-US-783 covers reading alone. The model names no caller of the method: it lists the consumers of the event, BlueprintService (AttachValidation), PipelineExecutionService (LinkValidation), FeedbackService, QualityScoreService and StudioBff, and no service whose dependency on ArtifactService is the recording of a verdict. The method therefore admits any workload whose token holds the service scope naming ArtifactService, and which workload records verdicts is reported to the owner. Refusals: UNAUTHENTICATED without a workload identity, PERMISSION_DENIED without the service scope or for an artifact of another project of the tenant, INVALID_ARGUMENT for a request without an artifact identifier or without a validationRef, and NOT_FOUND for an identifier the tenant of the caller does not hold, which is also the answer for an artifact of another tenant (ADR-0015). When artifact-sql is unavailable the call fails with UNAVAILABLE and nothing is recorded. The validation record itself is content and stays where its reference points; the event and the telemetry carry the reference and the verdict only.
Acceptance criteria
| AC1 | Given an ArtifactService/Artifact in state Stored and a workload of its tenant and project with the service scope, when ArtifactService/Artifacts.RecordValidation is called with a verdict and a validationRef, then the artifact moves to Validated through ValidationRecorded with validationRef set and the verdict kept, the reply is ack-v1 stating accepted, and ArtifactService/ArtifactValidated with artifactId, tenantId, passed and validationRef is written in the same transaction, for a passing and for a failing verdict alike; the artifact-v1 metadata of the artifact, which carried no passed and showed validation.status unvalidated before, carries passed and validationRef and shows validation.status valid for the passing and invalid for the failing verdict (SCN-ArtifactService-008, ADR-0014). |
| AC2 | Given that Validated artifact, when the same verdict with the same reference is recorded again, then the reply states accepted and no row or outbox record changes, and the same repeat is accepted without a change after the artifact was superseded and after it was deleted, because it still carries that validationRef; and when another verdict or reference is recorded for an artifact that carries a verdict, or any verdict for a Superseded or a Deleted artifact that carries none, then the reply is ack-v1 stating conflict, the artifact is unchanged and no event is written, because model/services/knowledge/ArtifactService.yaml has no transition for it (SCN-ArtifactService-008). |
| AC3 | Given a caller without a workload identity, a token without the service scope, a workload that forwards another project of the tenant, a request without an artifact identifier or without a validationRef, or an identifier the tenant of the caller does not hold, when ArtifactService/Artifacts.RecordValidation is called, then it is refused with UNAUTHENTICATED, PERMISSION_DENIED, PERMISSION_DENIED, INVALID_ARGUMENT and NOT_FOUND respectively, an artifact of another tenant, a tenant-level artifact of the platform tenant included, is answered NOT_FOUND exactly as an unknown one, a call made while artifact-sql does not answer fails with UNAVAILABLE, and in none of these cases a state changes or an event is written (SCN-ArtifactService-008, ADR-0015). |
| AC4 | Given the outbox record of a recorded verdict, when the dispatcher of the artifact messaging profile publishes ArtifactService/ArtifactValidated on artifacts.artifacts.v1.artifact-validated, then the event is sent in the run event envelope with artifactId, tenantId, passed and validationRef and without the content of the validation record, and a transport outage is retried with backoff so that the event is neither lost nor duplicated under its event id (SCN-ArtifactService-010, ADR-0012). |
| Traces: services | ArtifactService |
| Traces: aggregates | ArtifactService/Artifact |
| Traces: apis | ArtifactService/Artifacts.RecordValidation |
| Traces: events | ArtifactService/ArtifactValidated |
| Traces: descriptors | artifact-v1, ack-v1, run-event-envelope-v1 |
| Traces: adrs | ADR-0012, ADR-0014, ADR-0015 |
| Traces: requirements | FR-08 |
| Traces: scenarios | SCN-ArtifactService-008, SCN-ArtifactService-010 |
| Relates: nfrs | NFR-05 |
| Depends on | AIFACTORY-US-783, AIFACTORY-US-784 |
| Sources | model/services/knowledge/ArtifactService.yaml, docs/planes/knowledge-memory/services/artifact-service/index.md#domain-model |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-3162 Migration of the verdict column Passed on Artifacts |
migration | A migration adds to Artifacts the nullable column Passed of model/services/knowledge/ArtifactService.yaml (D125), the verdict of the recorded validation beside ValidationRef, and the aggregate receives the field passed; the column is the persisted validation status from which the member validation.status of artifact-v1 is read, unvalidated while it is empty, valid for a passed and invalid for a failed verdict; the mapping carries it under the tenant row filter and the mapping test runs against an isolated test database. | ConnectSoft.AI.SoftwareFactory.ArtifactService |
AIFACTORY-TASK-3163 Artifacts.RecordValidation with the Validated transition, the conflict acknowledgement and the ArtifactValidated outbox record |
implementation | Artifacts.RecordValidation applies ValidationRecorded to a Stored artifact, sets validationRef and the field passed and writes ArtifactValidated with artifactId, tenantId, passed and validationRef in one transaction, and replies ack-v1 accepted; the artifact-v1 metadata then carries passed and validationRef and shows validation.status valid or invalid, read from passed; a repeat of the recorded verdict and reference replies accepted and writes nothing in every state that still carries that validationRef, a superseded and a deleted artifact included; another verdict or reference for an artifact that carries a verdict and any verdict for a Superseded or Deleted artifact that carries none reply ack-v1 conflict and write nothing; UNAUTHENTICATED, PERMISSION_DENIED (a missing service scope and another project of the tenant), INVALID_ARGUMENT, NOT_FOUND (also for an artifact of another tenant and for a tenant-level artifact of the platform tenant, ADR-0015) and UNAVAILABLE while artifact-sql does not answer are given as AIFACTORY-US-786 states. | ConnectSoft.AI.SoftwareFactory.ArtifactService |
AIFACTORY-TASK-3164 Verify record-a-validation-verdict-on-an-artifact through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-ArtifactService-008\|Scenario=SCN-ArtifactService-010)"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-786: a passing and a failing verdict with validation.status shown as valid and invalid, the idempotent repeat for a Validated artifact and for the same artifact after it was superseded and after it was deleted, the conflict acknowledgement for another verdict on a Validated artifact and for a Superseded and a Deleted artifact without a verdict, every refusal with the fixture of AIFACTORY-TASK-3154, PERMISSION_DENIED for a workload that forwards another project of the tenant and UNAVAILABLE with artifact-sql stopped among them, and the publication and payload of ArtifactValidated; consumer handling is proven by the suites of the consumers. |
ConnectSoft.AI.SoftwareFactory.ArtifactService |
AIFACTORY-US-787: Read the metadata and lineage of an artifact, its version chain and the artifacts a run produced, and mark the outputs of a completed run¶
behavior · persona requester
As a requester, I want to see what an artifact is, what it derived from, which version of its chain it is and which artifacts my run produced, so that I can trust and explain an output without reading stored content I have no right to.
Three REST reads show what the store holds about an artifact; none of them returns content inline and none writes. GetArtifact under the scope factory.artifacts.read returns the metadata of one artifact as artifact-v1, its lineage edges, its position in the version chain (chainId, versionInChain, the latest version of the chain and the state), its validation as the member validation.status of artifact-v1 (unvalidated before a verdict, valid for a passed and invalid for a failed one, as AIFACTORY-US-786 records it) with validationRef as the details reference, and a scoped download reference. No operation of the model serves content over REST, so that reference is resolved by the blob store itself and not by the service: it is a delegated, read-only reference of the blob store for the one blob of this artifact, signed for a limited time, and it carries no account credential and is never the bare blob path. Its form and its lifetime are not in the model, so the lifetime is a configuration value the model does not list and both are reported to the owner. The suite proves the three properties: the reference returns the bytes of this artifact, it fails for another blob of the same tenant, and it fails after the configured lifetime on the clock of the suite. A Deleted artifact is returned with the state Deleted, its metadata and its lineage and without a download reference, so that a reference to it stays explainable. ListArtifactVersions under the same scope returns the version chain of the addressed artifact: every version in ascending order with artifactId, versionInChain, contentHash, state and createdAt. ListRunArtifacts under the scope factory.runs.read returns the artifacts whose producerRunId is the run, each with its state, its validation.status and the mark of a final output. A tenant-level artifact names no project, so no project role admits a user token to it: the three reads serve it only to a token with the tenant-wide Platform admin role of its tenant, as AIFACTORY-US-783 states, and the read admission of the platform tenant does not extend to these routes. A person reaches these routes through the Knowledge gateway, which feature knowledge-host delivers in this increment (D125); the acceptance suite of this feature calls the hosted routes with user tokens of that audience. A call without a token is answered 401 by the profile, and a token without the scope of the route is answered 403. For GetArtifact and ListArtifactVersions a token without a role in the project of the artifact is answered 403 as well, and an artifactId the tenant of the caller does not hold is answered 404, which is also the answer for an artifact of another tenant and never confirms that it exists (ADR-0015). ListRunArtifacts has the codes 200 and 403 in the model and no 404 (D125). The service holds no record of runs, only of artifacts, and a list holds only the artifacts of the projects the token grants: a runId of which the service holds no artifact visible to the caller is answered 200 with an empty list, which covers an unknown run, a run of another tenant, a run of a project the token does not grant and a run that produced nothing yet, so the answer never confirms that a run exists. When artifact-sql does not answer, a read is answered 503 with a problem response. The same PBI delivers the inbox handler SealRunArtifacts of RunCompleted of RunControlService, whose purpose in the model is to mark the artifacts of the run as final outputs and to close open chains. The handler is idempotent on the event id, runs under the tenant of the envelope and marks every artifact whose producerRunId is the run as a final output and every chain whose latest version that run produced as closed. The mark is the field finalOutput of the aggregate, the column FinalOutput of Artifacts, and a closed chain is the column Closed of VersionChains; both are in the model (D125) and the migration of this PBI creates them. What a closed chain refuses is not decided by the model: nothing is refused on it in this delivery, a later store under the same name still appends a version, and the point is reported to the owner. The handler writes no event, and an event for a run without artifacts is acknowledged without effect.
Acceptance criteria
| AC1 | Given a caller with factory.artifacts.read and a role in the project of a Validated ArtifactService/Artifact with two lineage edges that is version 2 of its chain, when ArtifactService/GetArtifact is called, then the response is 200 with its metadata, both lineage edges, chainId, versionInChain 2, the latest version of the chain, the state Validated, validation.status valid with validationRef as its details reference, and a delegated, read-only download reference of the blob store without an account credential, which returns the bytes of this artifact, fails for another blob of the tenant and fails after the configured lifetime on the clock of the suite; and for a Deleted artifact the response is 200 with the state Deleted, metadata and lineage and no download reference (SCN-ArtifactService-001, FUX-06). |
| AC2 | Given a chain of three versions of which the first two are Superseded, when ArtifactService/ListArtifactVersions is called with the artifactId of any of them, then the response is 200 with the three versions in ascending order, each with artifactId, versionInChain, contentHash, state and createdAt, and nothing is written (SCN-ArtifactService-003). |
| AC3 | Given artifacts produced by two runs in two projects of one tenant and a caller with factory.runs.read and a role in one of the projects, when ArtifactService/ListRunArtifacts is called for the run of that project, then the response is 200 with exactly the artifacts whose producerRunId is that run, each with its state, its validation.status and its final-output mark, and no artifact of the other run or project (SCN-ArtifactService-004). |
| AC4 | Given a token without the scope of the route, a token without a role in the project of the artifact, or an artifactId the tenant does not hold, when one of the three reads is called, then the response is 403, 403 and 404 respectively with a problem response, an artifact of another tenant is answered 404 exactly as an unknown one, and no state changes; and given a runId of which the service holds no artifact visible to the caller, that is an unknown run, a run of another tenant, a run of a project the token does not grant or a run that produced nothing yet, when ArtifactService/ListRunArtifacts is called, then the response is 200 with an empty list in each case and never 404 (SCN-ArtifactService-001, SCN-ArtifactService-003, SCN-ArtifactService-004, ADR-0015). |
| AC5 | Given a RunControlService/RunCompleted for a run that produced three artifacts in two chains, when SealRunArtifacts handles it, then the three artifacts are marked as final outputs and the two chains as closed in one transaction, ArtifactService/ListRunArtifacts shows the mark, a redelivery of the same event id changes nothing, an event for a run without artifacts is acknowledged without effect, and no event is written (model/services/knowledge/ArtifactService.yaml). |
| Traces: services | ArtifactService, RunControlService |
| Traces: aggregates | ArtifactService/Artifact |
| Traces: apis | ArtifactService/GetArtifact, ArtifactService/ListArtifactVersions, ArtifactService/ListRunArtifacts |
| Traces: events | RunControlService/RunCompleted |
| Traces: descriptors | artifact-v1 |
| Traces: adrs | ADR-0015, ADR-0019 |
| Traces: requirements | FR-08, FUX-06 |
| Traces: scenarios | SCN-ArtifactService-001, SCN-ArtifactService-003, SCN-ArtifactService-004 |
| Relates: screens | artifacts, run-detail |
| Depends on | AIFACTORY-US-782, AIFACTORY-US-783, AIFACTORY-US-784, AIFACTORY-US-786, feature:run-control-service |
| Sources | model/services/knowledge/ArtifactService.yaml, model/services/control-plane/RunControlService.yaml, docs/planes/knowledge-memory/services/artifact-service/index.md#apis, docs/planes/knowledge-memory/services/artifact-service/index.md#messages |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-3165 GetArtifact and ListArtifactVersions with lineage, chain position, validation and the scoped download reference |
implementation | GetArtifact returns the artifact-v1 metadata, the lineage edges, chainId, versionInChain, the latest version of the chain, the state, validation.status (unvalidated, valid or invalid) with validationRef as the details reference, and a download reference that the content port issues for the one blob of this artifact: a delegated, read-only reference of the blob store that the blob store resolves, signed for a lifetime set by a configuration value the model does not list, without an account credential; a tenant-level artifact is served only to a token with the tenant-wide Platform admin role of its tenant; a Deleted artifact is returned with its metadata and lineage and without a download reference; ListArtifactVersions returns every version of the chain in ascending order; both run under the tenant row filter, answer 403 for a missing scope or project role and 404 for an identifier the tenant does not hold, an artifact of another tenant included (ADR-0015), and write nothing. | ConnectSoft.AI.SoftwareFactory.ArtifactService |
AIFACTORY-TASK-3166 ListRunArtifacts and the SealRunArtifacts inbox handler with the final-output and closed-chain columns |
implementation | A migration adds the column FinalOutput to Artifacts and the column Closed to VersionChains, both of model/services/knowledge/ArtifactService.yaml (D125), and the aggregate receives the field finalOutput; the handler SealRunArtifacts of RunCompleted marks every artifact whose producerRunId is the run as a final output and every chain whose latest version the run produced as closed, in one transaction, idempotently on the event id and under the tenant of the envelope, writes no event and refuses nothing on a closed chain; ListRunArtifacts returns the artifacts of the run in the projects the token grants with state, validation and the final-output mark, answers 403 for a token without factory.runs.read and answers 200 with an empty list for a runId of which the service holds no artifact visible to the caller (D125). | ConnectSoft.AI.SoftwareFactory.ArtifactService |
AIFACTORY-TASK-3167 Verify read-artifact-metadata-version-chain-and-run-artifacts through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-ArtifactService-001\|Scenario=SCN-ArtifactService-003\|Scenario=SCN-ArtifactService-004)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-787 with the fixture of AIFACTORY-TASK-3154, artifacts in every state, the download reference of AC1 that returns the bytes of its artifact, fails for another blob of the tenant and fails after the configured lifetime on the clock of the suite, a chain of three versions, two runs in two projects, the empty list of ListRunArtifacts for an unknown run, a run of another tenant, a run of a project the token does not grant and a run without artifacts, and a fixture publisher of RunCompleted built from the pinned contracts package, delivered once, twice and for a run without artifacts. |
ConnectSoft.AI.SoftwareFactory.ArtifactService |
AIFACTORY-US-788: Render the preview of an artifact as a projection under the scope and the classification rules, and relabel artifacts when a classification changes¶
behavior · persona reviewer
As a reviewer, I want to read a diff, a document or a report of a run as a rendered preview that shows only what my scope and its classification allow, so that I can judge an output without a second copy of its content being made and without seeing what is restricted.
PreviewArtifact under the scope factory.artifacts.read renders an artifact for reading: a diff, a document or a report. The preview is a projection. It is computed on request from the stored content with one of the renderers that Knowledge:Artifacts:PreviewRenderers enables, by default diff, markdown, json and report, chosen by the kind and the media type of the artifact through one mapping table of the repository. It is never stored, so a preview creates no artifact, no blob, no row and no event, and it never becomes a second copy of the content. Before anything is rendered the service has the preview decided through Policy.Decide of PolicyEngineService, the required, fail-fast dependency the model lists for classification and redaction on store and preview. The request is a policy-decision-v1 with the caller of the token as subject, that is the caller of the kind user with tenant, the project of the artifact and the roles of the token, and with the action members kind, target, sideEffectClass and classification. The action kind is preview, the value policy-decision-v1 lists for the preview of an artifact (D125), with the target artifact-preview, the side-effect class read and the classification of the artifact. Every outcome of the schema is mapped. The outcome allow shows the content. The outcome allow-with-constraints withholds it: the preview shows the reference of the content in its place, that is the hash, the size and the artifact identifier, because the service applies no constraint it cannot interpret and a reference discloses nothing. The outcomes deny and allow-with-approval are answered 403 with the decision id in the problem body; the service never grants or opens an approval. The text that an allowing decision lets through then passes the artifact projection profile of the pinned compliance library (feature component-compliance-factory-classifications), which redacts a restricted field in every case. docs/architecture/data-governance.md shows confidential content only under an explicit scope, and the model lists no scope beyond factory.artifacts.read for a preview, so this PBI takes that explicit scope from the outcome of the decision, allow for the content and allow-with-constraints for the reference, and the point is reported to the owner. The response is 200 with the rendered preview and the name of the renderer. The model lists 200, 403 and 404 for the operation. 404 is the answer for an artifactId the tenant of the caller does not hold, which is also the answer for an artifact of another tenant, and for an artifact that has no preview: a Deleted artifact, whose content was removed, and an artifact whose kind and media type no enabled renderer serves. A token without the scope or without a role in the project of the artifact is answered 403. When PolicyEngineService or artifact-blob does not answer, the call is answered 503 with a problem response and nothing partial is returned. A person reaches the route through the Knowledge gateway, which feature knowledge-host delivers in this increment (D125); the suite of this feature calls the hosted route. No preview text reaches telemetry. The same PBI delivers the inbox handler ApplyClassification of ClassificationChanged of AuditService, whose purpose in the model is to re-label the stored artifacts of the affected scope. The event carries labelId, tenantId, resourceType, the optional resourceId, dataClass and retentionDays. The handler is idempotent on the event id and sets the classification of the artifacts of that tenant which the label addresses to the announced class: the one artifact resourceId names, or, for a type-level label without resourceId, every artifact the label covers. Classification is metadata: the relabel changes neither content nor hash, creates no version and writes no event, and the next preview and the next decision use the new class. Which values of resourceType address an artifact or an artifact kind is not fixed by the model, which types the member as a string; the handler reads them from one mapping that the contract test of the event pins, acknowledges a label of any other resource type without effect, and the point is reported to the owner. The retentionDays of the label is not applied to the sweep of AIFACTORY-US-789, because the model gives this handler the relabel only.
Acceptance criteria
| AC1 | Given a caller with factory.artifacts.read and a role in the project of a Markdown document ArtifactService/Artifact of class internal, when ArtifactService/PreviewArtifact is called, then the response is 200 with the rendered preview and the renderer markdown, and afterwards artifact-sql, artifact-blob and the outbox hold nothing they did not hold before, so that the preview is a projection and never a second copy (SCN-ArtifactService-002, FUX-06). |
| AC2 | Given a confidential artifact with a restricted field, when ArtifactService/PreviewArtifact is called and PolicyEngineService/Policy.Decide answers allow, then the content is shown with the restricted field redacted; when it answers allow-with-constraints, then the preview shows the reference of the content, its hash and its size in its place; when it answers deny or allow-with-approval, then the response is 403 with the decision id in the problem body; and the request the policy engine received was a policy-decision-v1 with the action kind preview, the target artifact-preview, the side-effect class read and the classification of the artifact (docs/architecture/data-governance.md, SCN-ArtifactService-002). |
| AC3 | Given a token without the scope, a token without a role in the project of the artifact, an artifactId the tenant does not hold, a Deleted artifact, or an artifact whose kind and media type no renderer of Knowledge:Artifacts:PreviewRenderers serves, when ArtifactService/PreviewArtifact is called, then the response is 403, 403, 404, 404 and 404 respectively with a problem response, and an artifact of another tenant is answered 404 exactly as an unknown one (SCN-ArtifactService-002, ADR-0015). |
| AC4 | Given PolicyEngineService or artifact-blob does not answer, when ArtifactService/PreviewArtifact is called, then the response is 503 with a problem response, nothing partial is rendered and nothing is written (SCN-ArtifactService-002, model/services/knowledge/ArtifactService.yaml). |
| AC5 | Given an AuditService/ClassificationChanged that names one artifact of a tenant and a new data class, when ApplyClassification handles it, then the classification of that ArtifactService/Artifact is the new class while its contentHash, its version and its state are unchanged and no event is written, a redelivery of the same event id changes nothing, a label of a resource type that addresses no artifact is acknowledged without effect, and no artifact of another tenant is touched (ADR-0019). |
| Traces: services | ArtifactService, PolicyEngineService, AuditService |
| Traces: aggregates | ArtifactService/Artifact |
| Traces: apis | ArtifactService/PreviewArtifact, PolicyEngineService/Policy.Decide |
| Traces: events | AuditService/ClassificationChanged |
| Traces: descriptors | policy-decision-v1 |
| Traces: adrs | ADR-0015, ADR-0019 |
| Traces: requirements | FUX-06, NFR-03 |
| Traces: scenarios | SCN-ArtifactService-002 |
| Relates: screens | artifacts |
| Relates: nfrs | NFR-03 |
| Depends on | AIFACTORY-US-782, AIFACTORY-US-783, AIFACTORY-US-784, feature:policy-engine-service, feature:audit-service-complete, feature:component-compliance-factory-classifications |
| Sources | model/services/knowledge/ArtifactService.yaml, model/services/governance/AuditService.yaml, model/services/governance/PolicyEngineService.yaml, docs/architecture/data-governance.md#classification, docs/planes/knowledge-memory/services/artifact-service/index.md#options-and-configuration |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-3168 PreviewArtifact with renderer selection, policy decision and the artifact projection profile |
implementation | PreviewArtifact selects a renderer of Knowledge:Artifacts:PreviewRenderers by kind and media type through one mapping table, has the preview decided through Policy.Decide with a policy-decision-v1 request whose action carries the kind preview (D125), the target artifact-preview, the side-effect class read and the classification of the artifact, and maps the four outcomes: for allow it renders the content read through the content port and passes the result through the artifact projection profile of the pinned compliance library, so that a restricted field is always redacted; for allow-with-constraints it returns the reference, the hash and the size in place of the content; for deny and allow-with-approval it answers 403 with the decision id in the problem body; it stores nothing; it answers 403 for a missing scope and a missing project role, 404 for an identifier the tenant does not hold, an artifact of another tenant included (ADR-0015), a Deleted artifact and an artifact without a renderer, and 503 while the policy engine or the blob store does not answer. | ConnectSoft.AI.SoftwareFactory.ArtifactService |
AIFACTORY-TASK-3169 ApplyClassification inbox handler relabelling the artifacts a changed label addresses |
implementation | The handler of ClassificationChanged sets the classification of the artifact resourceId names, or of every artifact a type-level label covers, to the announced data class within the tenant of the event, idempotently on the event id, without a change of content, hash, version or state and without an event; the values of resourceType that address an artifact or an artifact kind are read from one mapping that a contract test of the event pins, and a label of another resource type is acknowledged without effect; retentionDays of the label is not applied. | ConnectSoft.AI.SoftwareFactory.ArtifactService |
AIFACTORY-TASK-3170 Preview documents per renderer, classified artifacts and a fixture publisher of ClassificationChanged |
fixture | The acceptance suite holds one document per renderer (a diff, a Markdown document, a JSON document and a report), an artifact of a media type no renderer serves, artifacts of each of the four classification classes with a restricted field and a marker text, the fake of Policy.Decide of AIFACTORY-TASK-3158 set to each of the four outcomes allow, allow-with-constraints, deny and allow-with-approval, and a fixture publisher of ClassificationChanged built from the pinned contracts package for one artifact, for a type-level label and for a resource type that addresses no artifact. | ConnectSoft.AI.SoftwareFactory.ArtifactService |
AIFACTORY-TASK-3171 Verify preview-an-artifact-as-a-redacted-projection through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-ArtifactService-002"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-788: one preview per renderer with nothing stored, the four outcomes of the policy decision with the asserted request members, that is the redacted content for allow, the reference for allow-with-constraints and 403 with the decision id for deny and allow-with-approval, every 403 and 404 with the fixture of AIFACTORY-TASK-3154, the 503 while the policy engine or the blob store is stopped, and the relabel on ClassificationChanged with its redelivery. |
ConnectSoft.AI.SoftwareFactory.ArtifactService |
AIFACTORY-US-789: Remove the content of a deleted artifact, keep its metadata and lineage and announce the deletion with evidence; sweep content past its retention that no evidence record or unexpired run references¶
behavior · persona workspace-admin
As a workspace admin, I want the content of a deleted artifact removed while its record and its lineage stay, and content past the retention of my tenant swept unless an audit evidence record or an unexpired run still references it, so that every reference to a deleted artifact can still be explained, and the retention of my tenant is enforced without content being deleted that evidence or a run still needs.
Content does not stay for ever, and when it is removed its record stays. In this increment content is removed on two paths: by the retention sweep, which is effective in I1 (D125) and delivers the retention outcome of ADR-0019 decision 4, and for the artifacts of a closing project (AIFACTORY-US-790). The command Delete of the aggregate moves an artifact from Stored, Validated or Superseded to Deleted, keeps the row with its metadata and every lineage edge, and writes, in the same transaction, ArtifactDeleted with artifactId, tenantId and reason to the outbox together with one evidence record of the deletion. Audit evidence is an event: the sink of the pinned audit library (feature component-audit-factory-evidence) writes an audit-evidence-v1 record as AuditEvidenceSubmitted on audit.evidence.v1.evidence-submitted in the transaction of the command, with the actor, the artifact and its hash as subject, the deletion action the schema names and the reason, and without content. The same transaction sets a pending removal on the artifact. The pending removal is the field pendingRemoval of the aggregate, the column PendingRemoval of Artifacts: the model defines it as the state between Deleted and the removed blob (D125), and the migration of this PBI creates the column. After that transaction committed, the content is removed from artifact-blob. Content is held once per tenant and hash and several artifacts may reference it, so the removal runs under the lock of tenant and hash that a store takes as well (AIFACTORY-US-784) and checks again under it whether another artifact of the tenant with that hash still holds content. When one does, the blob stays and the pending removal is cleared, because the deletion of the last holder will remove the blob. When none does, the blob is removed, and the transaction that clears the pending removal lets connectsoft.factory.artifacts.bytes fall by its size. When the blob store does not answer, the artifact stays Deleted, Artifacts.Fetch already refuses it, the pending removal stays set and no second event is written. The removal is retried under the idempotency key artifactId by the retry policy of the worker that applied the deletion. When those attempts are used up, the work is visible as failed work to the worker operations that ADR-0015 defines, and the pending removal still stands: every run of RetentionSweeper selects the Deleted artifacts with a pending removal beside its retention candidates and tries their removal again, so a blob whose removal failed is removed on a later run without an operator, and only a cleared pending removal counts as a completed deletion. connectsoft.factory.artifacts.deleted counts the deletion by tenant and reason. Two paths apply the command in this delivery. The first is the worker RetentionSweeper, hosted by AIFACTORY-US-782 on its daily schedule, which the model defines as deleting content past the retention that no audit evidence record and no unexpired run references, with the reason of the retention expiry. The retention is the value of the option Knowledge:Artifacts:DefaultRetentionDays, 365 by default and reloadable, the one year of ADR-0019 decision 4; the retention of a project applies when a retention rule sets one, and such a rule arrives only with RetentionResidencyService in I4, so in this increment the default applies to every project artifact. A candidate is a project artifact that holds content, in state Stored, Validated or Superseded, and whose createdAt is older than the retention. A tenant-level artifact has no project and therefore no project retention, and is no candidate (D125). The service keeps its own records of the references that spare a candidate, the rows of the table ArtifactReferences, which AIFACTORY-US-986 writes from the audit evidence event and from the stores and the run end events of a run. The sweeper reads them and nothing else. A candidate with a reference record of the kind audit-evidence is spared. A candidate with a reference record of the kind run is spared while that run is unexpired. D125 does not say when a run expires, so this delivery reads it on the safe side, because deleting content cannot be undone: a run is unexpired while its record carries no RunEndedAt, and after its end until the retention has passed since RunEndedAt. That reading is reported to the owner. Every other candidate is deleted. A reference record written between the selection and the deletion still spares its artifact, because the sweeper checks the reference records of the artifact again in the transaction in which it applies Delete. Each run writes one log record per tenant with the number of candidates, the number a reference spared and the number deleted, and the activity of the run carries the three numbers, without content; the deletions are counted in connectsoft.factory.artifacts.deleted with the reason of the retention expiry. The second path is the deletion of the artifacts of a closing project (AIFACTORY-US-790), with the reason of the closing; the reference records concern the retention sweep alone, as the model states them, and are not read on this path. A third path arrives later: the handler of a deletion order is built in I4 with RetentionResidencyService and is not registered here, and with it arrive the handlers of a retention rule and of a legal hold, so in this increment no legal hold exists. No operation of the model deletes one artifact on request: the scope factory.artifacts.admin is summarised as export and delete, yet no REST or gRPC operation deletes, and AgentRuntimeService has no operation by which it could have the blob of a compacted checkpoint removed; both are reported to the owner. The sweeper follows the retry policy of the model, three attempts at a fixed interval, after which the failed work is visible to the worker operations that ADR-0015 defines; an artifact that is already Deleted is never deleted again and is selected only while its removal is pending, and a duplicate trigger deletes nothing twice.
Acceptance criteria
| AC1 | Given an ArtifactService/Artifact that holds content, in state Stored, Validated or Superseded, when Delete is applied to it, then it is Deleted, its row and its lineage edges remain, ArtifactService/ArtifactDeleted with artifactId, tenantId and reason, one audit-evidence-v1 record and the pending removal of the artifact were written in the same transaction, the content is removed from artifact-blob after the commit and the pending removal is cleared with it, ArtifactService/Artifacts.Fetch refuses the artifact and ArtifactService/GetArtifact returns it with the state Deleted (SCN-ArtifactService-012, ADR-0019). |
| AC2 | Given two artifacts of one tenant in two chains that reference the same content, when the first is deleted, then the blob stays, the pending removal of the first is cleared and the second is still fetched; and when the second is deleted, then the blob is removed and connectsoft.factory.artifacts.bytes falls once by its size (model/services/knowledge/ArtifactService.yaml). |
| AC3 | Given project artifacts younger and older than Knowledge:Artifacts:DefaultRetentionDays, of which one older artifact is referenced by an audit evidence record, one by a run that is not over, one by a run that ended within the retention and one by a run that ended before it, and a tenant-level artifact older than the retention, when RetentionSweeper runs with the reference records of ArtifactReferences, then exactly the older project artifacts that hold content and that no audit evidence record and no unexpired run references are deleted with the reason of the retention expiry, the artifact of the run that ended before the retention among them, the three referenced artifacts, the younger ones and the tenant-level one keep their content, a changed value of the option is applied by the next run, a second run and a duplicate trigger delete nothing more, and every run writes one log record per tenant and carries on its activity the numbers of candidates, spared and deleted (SCN-ArtifactService-012, model/services/knowledge/ArtifactService.yaml). |
| AC4 | Given the blob store does not answer when content is to be removed, when the removal is retried under the key artifactId, then the artifact stays Deleted with its pending removal set and refused by ArtifactService/Artifacts.Fetch, no second ArtifactService/ArtifactDeleted is written, after three failed attempts the work is visible as failed work of the worker, and the next run of RetentionSweeper selects the artifact again by its pending removal and removes the blob once the store answers; while the blob store is stopped the pending removal is never cleared, so the deletion does not count as complete, a closing project that waits for it stays Closing and no confirmation is written, and after the recovery the cleared pending removal lets one confirmation be written, which AC4 of AIFACTORY-US-790 proves end to end (SCN-ArtifactService-012, model/services/knowledge/ArtifactService.yaml). |
| AC5 | Given the outbox record of a deletion, when the dispatcher of the artifact messaging profile publishes ArtifactService/ArtifactDeleted on artifacts.artifacts.v1.artifact-deleted, then the event is sent in the run event envelope with artifactId, tenantId and reason and without content, and a transport outage is retried with backoff so that the event is neither lost nor duplicated under its event id (SCN-ArtifactService-012, ADR-0012). |
| Traces: services | ArtifactService |
| Traces: aggregates | ArtifactService/Artifact |
| Traces: apis | ArtifactService/Artifacts.Fetch, ArtifactService/GetArtifact |
| Traces: events | ArtifactService/ArtifactDeleted |
| Traces: descriptors | audit-evidence-v1, run-event-envelope-v1 |
| Traces: adrs | ADR-0012, ADR-0014, ADR-0019 |
| Traces: requirements | NFR-03, XL-14 |
| Traces: scenarios | SCN-ArtifactService-012 |
| Relates: nfrs | NFR-03, NFR-05 |
| Depends on | AIFACTORY-US-782, AIFACTORY-US-783, AIFACTORY-US-784, AIFACTORY-US-785, AIFACTORY-US-986, feature:component-audit-factory-evidence |
| Sources | model/services/knowledge/ArtifactService.yaml, docs/architecture/data-governance.md#retention-and-deletion, docs/architecture/adr/0019-data-governance.md, docs/reference/schemas/audit-evidence.schema.json, docs/planes/knowledge-memory/services/artifact-service/index.md#workers-and-jobs |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-3172 Delete command with the ArtifactDeleted outbox record, the evidence record and the repeatable removal of content |
implementation | The Delete command moves a Stored, Validated or Superseded artifact to Deleted, keeps the row and the lineage edges, and in one transaction sets the pending removal of the artifact and writes ArtifactDeleted with artifactId, tenantId and reason and one audit-evidence-v1 record through the sink of the pinned audit library as AuditEvidenceSubmitted on audit.evidence.v1.evidence-submitted, without content; after the commit the removal step takes the lock of tenant and hash that a store takes as well, checks again whether another artifact of the tenant with that hash still holds content, removes the blob through the content port when none does, and clears the pending removal in a transaction that lets connectsoft.factory.artifacts.bytes fall by the size of a removed blob and in which a participant that AIFACTORY-US-790 registers writes the confirmation of a closing project when the last pending removal of that project is cleared; a removal that fails leaves the pending removal set and writes no second event; connectsoft.factory.artifacts.deleted counts the deletion by tenant and reason. | ConnectSoft.AI.SoftwareFactory.ArtifactService |
AIFACTORY-TASK-3188 Migration of the pending-removal column PendingRemoval on Artifacts |
migration | A migration adds to Artifacts the column PendingRemoval of model/services/knowledge/ArtifactService.yaml (D125), which marks a pending removal of content, and the aggregate receives the field pendingRemoval: the Delete transaction sets it and the successful removal, or the finding that another artifact still holds the content, clears it; the selection of Deleted artifacts with a pending removal runs per tenant; the mapping carries the column under the tenant row filter and the mapping test runs against an isolated test database. | ConnectSoft.AI.SoftwareFactory.ArtifactService |
AIFACTORY-TASK-3173 RetentionSweeper selection by the default retention with the reference records, the run counts and the retry of pending removals |
implementation | RetentionSweeper selects, per tenant, the project artifacts that hold content and whose createdAt is older than the retention, the value of Knowledge:Artifacts:DefaultRetentionDays (365 by default, reloadable, read on every run) while no retention rule sets a project retention, reads the reference records of ArtifactReferences for each and applies Delete with the reason of the retention expiry to every candidate that no record of the kind audit-evidence and no record of the kind run of an unexpired run references; a run is unexpired while its record carries no RunEndedAt and until the retention has passed since RunEndedAt, a reading of D125 that is reported to the owner; the reference records are checked again in the transaction that applies Delete; the sweep is effective in I1 (D125) and no binding spares every artifact; each run writes one log record per tenant with the numbers of candidates, spared and deleted and sets the three on its activity, without content and without a new instrument; on every run the sweeper also selects the Deleted artifacts with a pending removal and runs the removal step of AIFACTORY-TASK-3172 for each; a tenant-level artifact is no candidate, an artifact already Deleted is never deleted again, a duplicate trigger has no second effect, and after three failed attempts the work is shown to the worker operations that ADR-0015 defines. | ConnectSoft.AI.SoftwareFactory.ArtifactService |
AIFACTORY-TASK-3174 Aged artifacts, a controllable clock, reference records of both kinds and a failing blob removal |
fixture | The acceptance suite holds a clock it sets, project artifacts created before and after the retention of Knowledge:Artifacts:DefaultRetentionDays in each state, a tenant-level artifact older than the retention, two artifacts of one tenant that reference the same content, reference records written through the handlers of AIFACTORY-US-986 with the fixture of AIFACTORY-TASK-3974 for an older artifact that an audit evidence record references, one whose run is not over, one whose run ended within the retention and one whose run ended before it, a second value of the option, the blob store double of AIFACTORY-TASK-3158 set to refuse a removal a given number of times and to stay stopped across a run of the sweeper, a recording participant of the transaction that clears a pending removal, a reader of the log records and the activity of a sweeper run, and a subscriber on artifacts.artifacts.v1.artifact-deleted and on audit.evidence.v1.evidence-submitted that records every delivered envelope. | ConnectSoft.AI.SoftwareFactory.ArtifactService |
AIFACTORY-TASK-3175 Verify delete-artifact-content-keep-metadata-and-lineage through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-ArtifactService-012"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-789: the three Deleted transitions with the kept row and lineage, the evidence record, the pending removal set with the deletion and cleared with the removed blob, the shared content removed with its last holder, the sweep by the default retention that deletes exactly the older project artifacts no audit evidence record and no unexpired run references, the artifact of a run that ended before the retention among them, and spares the artifact an evidence record references, the artifacts of a run that is not over and of a run that ended within the retention, the younger artifacts and the tenant-level artifact, the changed value of Knowledge:Artifacts:DefaultRetentionDays applied by the next run, the log record and the activity of each run with the numbers of candidates, spared and deleted, the removal that fails three times, stays pending and succeeds on the next run of the sweeper, the pending removal that is never cleared while the blob store is stopped and whose clearing transaction calls its registered participant once after the recovery, and the publication and payload of ArtifactDeleted; consumer handling is proven by the suites of the consumers. |
ConnectSoft.AI.SoftwareFactory.ArtifactService |
AIFACTORY-US-790: Export the artifacts, metadata and lineage of a project in open formats, and confirm the export or the deletion of a closing project¶
behavior · persona workspace-admin
As a workspace admin, I want the artifacts of my project exported with their metadata and lineage in open formats, on request and when the project closes, so that my tenant takes what it owns and a closing project ends only with a recorded export or deletion of its data.
A tenant owns what it submitted and what was derived from it, and takes it along on request (ADR-0019 decision 5). ExportArtifacts under the scope factory.artifacts.admin starts the export of the artifacts, the metadata and the lineage of one project; it is of class external and idempotent on the Idempotency-Key header. The caller is a Workspace admin of the project or a Platform admin. A person reaches the route through the Knowledge gateway, which feature knowledge-host delivers in this increment (D125); this feature builds no direct route, and its suite calls the hosted route. The service has the export decided through Policy.Decide of PolicyEngineService with the action kind export of policy-decision-v1, the target artifact-export and the side-effect class external. Whether an export needs an approval is decided by that decision alone: the service never decides, grants or assumes an approval. Every outcome of the schema is mapped. The outcome allow starts the export and the outcome deny is answered 403. For the outcome allow-with-approval the model lists no answer, since the operation has the codes 202, 403 and 404, and it names nobody who opens an approval request for an export asked outside a run; until the owner decides, such a call is answered 403 with the decision id in the problem body and nothing starts. The outcome allow-with-constraints is answered in the same way, because the service can apply no constraint to a package. An allowed call records an export request and answers 202 with its identifier. The request is a row of the table ExportRequests of the model (D125), which the migration of this PBI creates: request identifier, tenant, project, kind (export or deletion), origin (caller-request or project-closing), idempotency key, requester, state (requested, completed or failed), failure reason, the artifact of the package and the times of the request and of its completion. Two things are written in one transaction: the request row in the state requested and one evidence record of the request, which is an audit-evidence-v1 record written as AuditEvidenceSubmitted on audit.evidence.v1.evidence-submitted by the sink of the pinned audit library with the requester as actor and the project as subject. The recorded request is what starts the worker: the model names a row of ExportRequests in the state requested as a trigger of ExportWorker beside ProjectStateChanged of ProjectService, and no event announces it (D125). The service publishes no message for it, and a 202 is followed by a package without any event of ProjectService. The key is scoped by tenant and project: a repeat with the same key returns the same request with 202 and starts nothing, and since the request has no body the model defines, no second input can arrive under the same key. A project in which the tenant of the caller holds no version chain is answered 404, which is also the answer for a project of another tenant; a token without the scope or without a role in the project is answered 403. The worker ExportWorker picks up the requests in the state requested, as AIFACTORY-US-782 hosts it, and produces the package under the key of project and export request, one at a time per tenant; a request that is found again by a later look of the worker, or picked up again after an interrupted execution, builds one package, because the request is completed with its package in one transaction and a completed or failed request is never picked up again. The package follows docs/architecture/data-governance.md: records as JSON, that is the metadata of every artifact of the project, the Deleted ones included, the version chains and the lineage edges, content in its original format under its hash, and reports as Markdown. It is stored as one artifact of kind Export in the project through the path of AIFACTORY-US-784, so ArtifactStored announces it, and the request is marked completed with that artifact in the same transaction; the requester reads it through the download reference of GetArtifact. A package larger than Knowledge:Artifacts:MaxArtifactMb has no rule in the model and is reported to the owner. The worker retries as the model states, five attempts with exponential backoff, and then marks the request failed with its reason, leaves no partial package and shows the failed work to the worker operations that ADR-0015 defines; it never repeats an export beyond that policy on its own. The same worker serves a closing project. The inbox handler ExportOrDeleteOnClosing of ProjectStateChanged of ProjectService reacts to the transition to Closing, idempotently on the event id, and exports or deletes the artifacts of the project per tenant policy. Where that tenant policy is held is not named by the model: the handler reads the choice through one port, whose binding in this delivery is one configuration value per tenant that the model does not list, and without a value it exports, because an export destroys nothing; the source of the choice is reported to the owner. The handler only records the work and executes none of it: it writes one row of ExportRequests of the origin project-closing, of the kind export or deletion, in the state requested, with the workload identity of the service as requester. The column IdempotencyKey of the table is required and the model does not say which key such a record carries; this delivery writes the event id of the consumed ProjectStateChanged, so that the unique index on tenant, project and key refuses a second record of a redelivered event, and the point is reported to the owner. ExportWorker executes both kinds under the retry policy and the concurrency the model gives it, five attempts with exponential backoff and one execution at a time per tenant. On the export path it builds the package as for a requested export, and the transaction that marks the request completed writes ProjectDataOffboarded with projectId, tenantId and the outcome exported. On the deletion path it applies Delete to the artifacts of the project in batches, each batch in one transaction, with the reason of the closing and with everything AIFACTORY-US-789 describes for a deletion: the event, the evidence record and the pending removal of each artifact. The size of a batch is a configuration value the model does not list. A repeated execution skips the artifacts that are already Deleted, so a retry resumes where the failed attempt stopped; when the batches fail five times the request is marked failed and is visible as failed work. The outcome deleted has one meaning: every artifact of the project is in the state Deleted and none has a pending removal, so no blob of the project is left, because the invariant of the model confirms only a completed deletion. ProjectDataOffboarded with the outcome deleted is therefore written in the transaction that clears the last pending removal of the project, which marks the request completed as well. This PBI registers that step as a participant of the clearing transaction of AIFACTORY-US-789, so it runs whether the removal succeeds within the attempts of ExportWorker or on a later run of RetentionSweeper, and a request whose artifacts are all Deleted is not failed by a removal that is still pending. While the blob store does not answer, no pending removal is cleared, no confirmation is written and the project stays Closing; after the recovery one confirmation is written. A project without artifacts is confirmed by the first execution of its request with the outcome of the chosen path, because ProjectService moves the project to Closed only after this confirmation. One confirmation is written per closing project; a redelivered event, a request found twice by the worker and a duplicate trigger write none, and a failed export writes none, so the project stays Closing until the failed work is replayed.
Acceptance criteria
| AC1 | Given a Workspace admin with factory.artifacts.admin and a role in a project that holds artifacts, and an allowing decision of PolicyEngineService/Policy.Decide for the action kind export, when ArtifactService/ExportArtifacts is called with an Idempotency-Key, then the response is 202 with the export request, the row of ExportRequests in the state requested and one audit-evidence-v1 record of the request were written in one transaction, no message was published for the request, and a repeat with the same key returns the same request with 202 and starts no second export (SCN-ArtifactService-005, XL-14). |
| AC2 | Given a token without the scope, a token without a role in the project, a decision of PolicyEngineService/Policy.Decide with the outcome deny, allow-with-approval or allow-with-constraints, or a project in which the tenant holds no version chain, when ArtifactService/ExportArtifacts is called, then the response is 403, 403, 403 and 404 respectively with a problem response, which carries the decision id after a decision, a project of another tenant is answered 404 exactly as an unknown one, and no request, evidence record or package is written (SCN-ArtifactService-005, ADR-0015). |
| AC3 | Given an export request recorded by ArtifactService/ExportArtifacts as a row of ExportRequests in the state requested, when ExportWorker looks for recorded requests, then it picks the request up without any ProjectService/ProjectStateChanged and without any message, one ArtifactService/Artifact of kind Export exists in the project whose package holds the metadata, the version chains and the lineage edges as JSON and each content in its original format under its hash, as docs/architecture/data-governance.md states, ArtifactService/ArtifactStored announces it, the request is completed with that artifact in the same transaction, a request the worker finds a second time and a duplicate trigger build one package, and after five failed attempts the request is failed with its reason and no partial package exists (SCN-ArtifactService-005). |
| AC4 | Given a ProjectService/ProjectStateChanged that announces the transition of a project to Closing, when ExportOrDeleteOnClosing handles it, then the handler records one row of ExportRequests of the origin project-closing in the state requested and executes nothing itself; on the export path the completed export writes ArtifactService/ProjectDataOffboarded with the outcome exported in the transaction that completes the request; on the deletion path ExportWorker deletes the artifacts in batches and the confirmation with the outcome deleted is written in the transaction that clears the last pending removal of the project; with the blob store stopped the project stays Closing and no confirmation is written, and after its recovery one confirmation is written; a project without artifacts is confirmed by the first execution of its request; and a redelivery of the same event id writes no second confirmation (SCN-ArtifactService-013, XL-14). |
| AC5 | Given the outbox record of a confirmation, when the dispatcher of the artifact messaging profile publishes ArtifactService/ProjectDataOffboarded on artifacts.projects.v1.project-data-offboarded, then the event is sent in the run event envelope with projectId, tenantId and outcome, and a transport outage is retried with backoff so that the event is neither lost nor duplicated under its event id (SCN-ArtifactService-013, ADR-0012). |
| Traces: services | ArtifactService, PolicyEngineService, ProjectService |
| Traces: aggregates | ArtifactService/Artifact |
| Traces: apis | ArtifactService/ExportArtifacts, PolicyEngineService/Policy.Decide |
| Traces: events | ArtifactService/ProjectDataOffboarded, ArtifactService/ArtifactStored, ProjectService/ProjectStateChanged |
| Traces: descriptors | audit-evidence-v1, policy-decision-v1, run-event-envelope-v1 |
| Traces: adrs | ADR-0012, ADR-0014, ADR-0015, ADR-0019 |
| Traces: requirements | NFR-03, XL-14 |
| Traces: scenarios | SCN-ArtifactService-005, SCN-ArtifactService-013 |
| Relates: nfrs | NFR-03, NFR-05 |
| Depends on | AIFACTORY-US-782, AIFACTORY-US-783, AIFACTORY-US-784, AIFACTORY-US-787, AIFACTORY-US-789, feature:policy-engine-service, feature:project-service, feature:component-audit-factory-evidence |
| Sources | model/services/knowledge/ArtifactService.yaml, model/services/control-plane/ProjectService.yaml, docs/architecture/data-governance.md#retention-and-deletion, docs/reference/schemas/audit-evidence.schema.json, docs/reference/schemas/policy-decision.schema.json, docs/planes/knowledge-memory/services/artifact-service/index.md#workers-and-jobs |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-3176 Migration of the export request table ExportRequests in artifact-sql |
migration | A migration adds the table ExportRequests of model/services/knowledge/ArtifactService.yaml (D125) for export requests and for the work of a closing project, and the aggregate receives the entity ExportRequest: RequestId, TenantId, ProjectId, Kind (export or deletion), Origin (caller-request or project-closing), IdempotencyKey, RequestedBy, State (requested, completed, failed), FailureReason, PackageArtifactId with its foreign key to Artifacts, RequestedAt and CompletedAt, with the unique index UX_ExportRequests_Tenant_Project_Key on tenant, project and key, the index IX_ExportRequests_Tenant_State by which ExportWorker reads the requested rows, and the tenant row filter on its mapping; the mapping test runs against an isolated test database. | ConnectSoft.AI.SoftwareFactory.ArtifactService |
AIFACTORY-TASK-3177 ExportArtifacts with the policy decision, the evidence record and the ExportWorker package |
implementation | ExportArtifacts has the export decided through Policy.Decide with the action kind export, the target artifact-export and the side-effect class external, starts the export for the outcome allow only and answers 403 with the decision id for the outcomes deny, allow-with-approval and allow-with-constraints, answers 404 for a project without a version chain of the tenant, and for an allowed call writes in one transaction the row of ExportRequests of the origin caller-request in the state requested and one audit-evidence-v1 record through the sink of the pinned audit library, publishes no message for the request, and answers 202; a repeat with the same key in the same tenant and project returns the same request and writes no second row; ExportWorker picks the row up from ExportRequests as the model states (D125), so a recorded request reaches it without an event of ProjectService, and a request it finds a second time builds one package, because a completed or failed request is never picked up again; it builds the package with the records as JSON, each content in its original format under its hash and reports as Markdown, stores it as one artifact of kind Export through the store path with its ArtifactStored record, completes the request in the same transaction, and after five failed attempts marks the request failed and leaves no partial package. | ConnectSoft.AI.SoftwareFactory.ArtifactService |
AIFACTORY-TASK-3178 ExportOrDeleteOnClosing inbox handler that records the work of a closing project through the tenant choice port |
implementation | The handler of ProjectStateChanged reacts to the transition to Closing, idempotently on the event id, reads the choice between export and deletion through one port bound to a configuration value per tenant that the model does not list, and chooses the export when no value is set; it executes nothing itself: it writes one row of ExportRequests of the origin project-closing and of the kind export or deletion, in the state requested, with the workload identity of the service as requester and the event id of the consumed ProjectStateChanged as IdempotencyKey, a choice of this delivery that is reported to the owner because the model names no key for such a record, and publishes no message; a redelivered event writes no second request. | ConnectSoft.AI.SoftwareFactory.ArtifactService |
AIFACTORY-TASK-3189 Closing work of ExportWorker with the deletion in batches and the ProjectDataOffboarded confirmation on the last cleared pending removal |
implementation | ExportWorker executes a request of the origin project-closing, which it picks up from ExportRequests in the state requested, under its retry policy of five attempts with exponential backoff, one at a time per tenant: for the kind export it builds the package as for a requested export and writes ProjectDataOffboarded with the outcome exported in the transaction that completes the request; for the kind deletion it applies Delete to the artifacts of the project in batches of a configured size the model does not list, each batch in one transaction with the reason of the closing, the event, the evidence record and the pending removal of AIFACTORY-TASK-3172, skips artifacts that are already Deleted on a repeated execution, and runs the removal step for each; a participant registered in the transaction that clears a pending removal writes ProjectDataOffboarded with the outcome deleted and completes the request when it clears the last pending removal of a project whose artifacts are all Deleted, whether ExportWorker or a later run of RetentionSweeper clears it; with the blob store stopped no confirmation is written and the request stays open; a project without artifacts is confirmed by the first execution; one confirmation is written per closing project. | ConnectSoft.AI.SoftwareFactory.ArtifactService |
AIFACTORY-TASK-3179 Verify export-project-artifacts-and-confirm-offboarding through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-ArtifactService-005\|Scenario=SCN-ArtifactService-013)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-790 with the fake of Policy.Decide of AIFACTORY-TASK-3158 set to each of its four outcomes, a golden manifest of the package, a request recorded by ExportArtifacts that ExportWorker picks up from ExportRequests while no ProjectStateChanged and no message is published, a request the worker finds twice that builds one package, a fixture publisher of ProjectStateChanged built from the pinned contracts package and delivered once and twice, both bindings of the choice port, the deletion of a closing project in several batches, the blob store stopped during that deletion with the project left Closing and no confirmation on artifacts.projects.v1.project-data-offboarded, one confirmation after its recovery whether the worker or a run of RetentionSweeper clears the last pending removal, a project without artifacts, an export that fails five times, and the publication and payload of ProjectDataOffboarded; consumer handling is proven by the suite of ProjectService. |
ConnectSoft.AI.SoftwareFactory.ArtifactService |
AIFACTORY-US-986: Keep the reference records of audit evidence and of runs that spare an artifact from the retention sweep¶
behavior · persona workspace-admin
As a workspace admin, I want the artifact store to know by its own records which artifacts an audit evidence record or a run of my tenant references, so that the retention sweep deletes old content without removing what evidence or an unexpired run still points at.
The retention sweep is effective in I1 (D125), and deleting content cannot be undone, so the service must know which artifacts to spare before RetentionSweeper deletes anything. No other service is asked at the time of the sweep: ArtifactService keeps its own records, the entity ArtifactReference of the aggregate and the table ArtifactReferences of the model, and this PBI writes them; the sweep that reads them is delivered by AIFACTORY-US-789. A reference record names the artifact, the tenant, the kind of the reference, audit-evidence or run, the identifier of the evidence record or of the run as ReferenceRef, the time it was recorded and, for a run, the optional RunEndedAt. The unique index UX_ArtifactReferences_Artifact_Reference on artifact, kind and reference keeps one record per reference, and the index IX_ArtifactReferences_Tenant_Reference finds the records of one run or of one evidence record. The table has the tenant column and its mapping carries the tenant row filter of the profile (AIFACTORY-US-783). Three sources write or complete the records. The first is audit evidence. Every service writes its audit-evidence-v1 records to its own outbox, and they are delivered as AuditEvidenceSubmitted on audit.evidence.v1.evidence-submitted in the run event envelope, the topic from which AuditService appends them. The model states the consumption by ArtifactService as the command RecordEvidenceReference and not as a consumes row, because the evidence event is no modelled event of a service. The subscription is declared by AIFACTORY-US-782; the handler of this PBI runs under the tenant of the record and writes one reference record of the kind audit-evidence per evidence id and artifact, with the evidenceId as ReferenceRef. Which artifacts an evidence record references is read from its subject: the schema gives a subject a kind, an id and an optional hash and fixes no list of kinds, and D125 does not say which subject kinds name an artifact or whether the match is by identifier or by hash. This delivery records a reference when subject.id is the artifactId of an artifact of the tenant of the record, for the subject kinds of one mapping that the contract test of the event pins, and matches no hash; a record whose subject names no artifact of that tenant is acknowledged without effect, and the point is reported to the owner. A redelivered evidence record writes nothing, and this delivery never removes a reference record of the kind audit-evidence, because audit evidence is retained far longer than content (ADR-0019). The second source is the store. When the metadata of Artifacts.Store names a producer run, the transaction of the store (AIFACTORY-US-784) writes one reference record of the kind run for the new artifact, with the producerRunId as ReferenceRef and without RunEndedAt. This PBI registers that step as a participant of the store transaction, so the record commits or rolls back with the artifact, and an idempotent repeat of a store writes none. The producing run is the only run the service knows of: the model names no writer of a run reference, and D125 does not say whether a run that only fetched or pinned an artifact as an input counts or how the service would learn of it, which is reported to the owner. The third source is the end of a run. The inbox handler RecordRunEnd consumes RunCompleted, RunFailed and RunCancelled of RunControlService, idempotently on the event id and under the tenant of the envelope, and sets RunEndedAt on every reference record of the kind run whose ReferenceRef is that run, with the time the envelope of the event states, so that the sweep knows when a run that references an artifact is over. RunCompleted reaches two handlers of the service, SealRunArtifacts (AIFACTORY-US-787) and RecordRunEnd, each deduplicated on its own. A run end event for a run without reference records is acknowledged without effect, and a record that already carries RunEndedAt keeps it. The service holds no record of runs, so a store that names a run whose end was already announced writes a record without RunEndedAt, and that artifact stays spared; the case is on the safe side of a deletion and is reported to the owner. The handlers write no event and call no other service. A handler that fails is retried by the inbox with backoff and is never applied twice, and while artifact-sql does not answer nothing is recorded and the delivery is retried. An evidence record or a run end event of one tenant never touches a record of another tenant. No content, no subject identifier and no reason text of an evidence record reaches a log record, an activity or a metric. When a run reference stops sparing its artifact is a rule of the sweep and is stated with it (AIFACTORY-US-789).
Acceptance criteria
| AC1 | Given artifacts of two tenants and fixture evidence records published as AuditEvidenceSubmitted on audit.evidence.v1.evidence-submitted in the run event envelope, when the handler of the command RecordEvidenceReference receives a record whose subject.id is the artifactId of an ArtifactService/Artifact of the tenant of the record, then one row of ArtifactReferences of the kind audit-evidence exists for that artifact with the evidenceId as ReferenceRef, a redelivery of the same evidence id adds none, a record whose subject names no artifact of that tenant, an artifact of the other tenant included, or whose subject kind the pinned mapping does not list is acknowledged without effect, and no event is written (model/services/knowledge/ArtifactService.yaml, ADR-0019). |
| AC2 | Given a workload that calls ArtifactService/Artifacts.Store with a producer run in the metadata, when the store commits, then one row of ArtifactReferences of the kind run exists for the new artifact with the producerRunId as ReferenceRef and an empty RunEndedAt, written in the transaction of the store; a store that is rolled back leaves none, an idempotent repeat adds none, and a store without a producer run writes none (model/services/knowledge/ArtifactService.yaml, ADR-0014). |
| AC3 | Given reference records of the kind run for three runs, when RunControlService/RunCompleted, RunControlService/RunFailed and RunControlService/RunCancelled are delivered, one for each run, then RecordRunEnd sets RunEndedAt on every record of the run its event names, with the time the envelope states, and on no record of another run or of the kind audit-evidence; a redelivery of the same event id changes nothing, an event for a run without reference records is acknowledged without effect, RunControlService/RunCompleted is handled by SealRunArtifacts and by RecordRunEnd once each, and no event is written (model/services/knowledge/ArtifactService.yaml). |
| AC4 | Given reference records of two tenants and a handler whose transaction fails once, when an evidence record or a run end event of one tenant is delivered and the failed delivery is retried, then no row of the other tenant is read or changed under the tenant row filter, the retried delivery is applied once, a second record with the same artifact, kind and reference is refused by UX_ArtifactReferences_Artifact_Reference, and no subject identifier, reason text or content reaches a log record, an activity or a metric (ADR-0015, ADR-0019). |
| Traces: services | ArtifactService, RunControlService |
| Traces: aggregates | ArtifactService/Artifact |
| Traces: apis | ArtifactService/Artifacts.Store |
| Traces: events | RunControlService/RunCompleted, RunControlService/RunFailed, RunControlService/RunCancelled |
| Traces: descriptors | audit-evidence-v1, run-event-envelope-v1 |
| Traces: adrs | ADR-0014, ADR-0015, ADR-0019 |
| Traces: requirements | NFR-03 |
| Relates: nfrs | NFR-03 |
| Depends on | AIFACTORY-US-781, AIFACTORY-US-782, AIFACTORY-US-783, AIFACTORY-US-784, feature:run-control-service, feature:contracts-package, feature:component-audit-factory-evidence |
| Sources | model/services/knowledge/ArtifactService.yaml, model/services/control-plane/RunControlService.yaml, model/services/governance/AuditService.yaml, docs/reference/schemas/audit-evidence.schema.json, docs/architecture/data-governance.md#retention-and-deletion, docs/architecture/adr/0019-data-governance.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-3971 Migration and mapping of the reference record table ArtifactReferences |
migration | A migration adds the table ArtifactReferences of model/services/knowledge/ArtifactService.yaml (D125), and the aggregate receives the entity ArtifactReference: ReferenceId, ArtifactId with its foreign key to Artifacts, TenantId, ReferenceKind (audit-evidence or run), ReferenceRef, the nullable RunEndedAt and RecordedAt, with the unique index UX_ArtifactReferences_Artifact_Reference on artifact, kind and reference and the index IX_ArtifactReferences_Tenant_Reference on tenant, kind and reference; the mapping carries the tenant row filter of the Factory profile and the mapping test runs against an isolated test database, never a shared one. | ConnectSoft.AI.SoftwareFactory.ArtifactService |
AIFACTORY-TASK-3972 RecordEvidenceReference handler of the audit evidence event |
implementation | The handler of the command RecordEvidenceReference receives AuditEvidenceSubmitted from audit.evidence.v1.evidence-submitted through the subscription of AIFACTORY-TASK-058, reads the audit-evidence-v1 record of the envelope under the tenant of the record and writes one row of ArtifactReferences of the kind audit-evidence, with the evidenceId as ReferenceRef, when subject.id is the artifactId of an artifact of that tenant and the subject kind is listed in one mapping that a contract test of the event pins; it matches no hash, acknowledges every other record without effect, is idempotent on the evidence id and on the unique index of the table, writes no event and puts no subject identifier, reason text or content into telemetry; which subject kinds name an artifact and whether a hash is to be matched are reported to the owner. | ConnectSoft.AI.SoftwareFactory.ArtifactService |
AIFACTORY-TASK-3973 Run reference record in the store transaction and the RecordRunEnd inbox handler of the three run end events |
implementation | A participant of the transaction of Artifacts.Store writes one row of ArtifactReferences of the kind run for a new artifact whose metadata names a producer run, with the producerRunId as ReferenceRef and an empty RunEndedAt, so the record commits or rolls back with the artifact and an idempotent repeat writes none; the handler RecordRunEnd of RunCompleted, RunFailed and RunCancelled of RunControlService sets RunEndedAt, the time the envelope of the event states, on every record of the kind run of that run and tenant that carries none, idempotently on the event id, acknowledges an event for a run without records without effect and writes no event; RunCompleted is delivered to SealRunArtifacts and to RecordRunEnd, each deduplicated on its own; a store that names a run whose end was already announced writes a record without RunEndedAt, which is reported to the owner with the question of which other runs reference an artifact. | ConnectSoft.AI.SoftwareFactory.ArtifactService |
AIFACTORY-TASK-3974 Fixture publishers of audit evidence records and of the three run end events |
fixture | The acceptance suite holds a fixture publisher of AuditEvidenceSubmitted on audit.evidence.v1.evidence-submitted, built from the pinned contracts package, for records whose subject names an artifact of the tenant, an artifact of another tenant, no artifact and a subject kind outside the pinned mapping, fixture publishers of RunCompleted, RunFailed and RunCancelled of RunControlService for runs with and without stored artifacts, each delivered once and twice, the builders of store streams of AIFACTORY-TASK-3158 with and without a producer run, a switch that fails the transaction of a handler once, and a reader of the rows of ArtifactReferences per tenant; the fixture also serves the sweep suite of AIFACTORY-US-789. | ConnectSoft.AI.SoftwareFactory.ArtifactService |
AIFACTORY-TASK-3975 Verify the reference records of audit evidence and of runs through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Feature=ReferenceRecords"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-986: one record per evidence id and artifact with its redelivery, the evidence records that name no artifact of the tenant or a subject kind outside the pinned mapping, the run record written and rolled back with a store and absent for a repeat and for a store without a producer run, RunEndedAt set by each of the three run end events on the records of its run only, the redelivered and the unmatched run end event, RunCompleted handled once by each of its two handlers, the two tenants kept apart, the retried handler applied once, the refused duplicate of UX_ArtifactReferences_Artifact_Reference and the scan of telemetry, against model/services/knowledge/ArtifactService.yaml. |
ConnectSoft.AI.SoftwareFactory.ArtifactService |