ArtifactService

Target

This page describes intended behaviour or structure. No implementation is claimed unless a section is explicitly marked Current implementation or Evidence.

Bounded context	BC-12 Artifacts & Lineage
Platform / plane	Knowledge Platform / Knowledge & Memory
Deployment granularity	module of host · host KnowledgeHost
Status	target · ConnectSoft.Factory.Knowledge.Artifacts
Built from	connectsoft-microservice · libraries: connectsoft-extensions-data-storage-abstractions, connectsoft-extensions-saas-abstractions, connectsoft-extensions-messaging-model, connectsoft-extensions-persistence-model-nhibernate, connectsoft-extensions-compliance
Decisions	ADR-0014, ADR-0019
Traceability	FR-08 FUX-06 NFR-03 NFR-05 NFR-16 XL-06 XL-14

Purpose and responsibilities

Everything the Factory produces or needs to keep as content is an artifact: documents, code and change sets, reports, logs, adapter checkpoints, release manifests, evaluation records, prompts and model outputs, export packages. ArtifactService stores content once by hash, records who produced it (run, attempt, agent), what it derived from (lineage edges to artifacts, chunks, context snapshots and receipts) and where it sits in a version chain; it renders previews and version history as projections. Because prompts and model outputs are artifacts, no other service ever holds content in its rows (D31).

It absorbs LineageService, VersioningService, ArtifactPreviewService and ArtifactMemoryService from the June-2026 catalog.

Context and boundaries

flowchart LR
    S["ArtifactService"]
    AgentRuntimeService["AgentRuntimeService"] -->|grpc| S
    ModelRouterService["ModelRouterService"] -->|grpc| S
    KnowledgeIngestionService["KnowledgeIngestionService"] -->|grpc| S
    ContextBuilderService["ContextBuilderService"] -->|grpc| S
    StudioBff["StudioBff"] -->|sync-http| S
    S -->|grpc| PolicyEngineService["PolicyEngineService"]
    S -->|grpc| CostUsageService["CostUsageService"]
    S -->|event| AuditService["AuditService"]
    S -. "ArtifactStored" .-> E_ArtifactStored(("event"))
    S -. "ArtifactValidated" .-> E_ArtifactValidated(("event"))
    S -. "ArtifactSuperseded" .-> E_ArtifactSuperseded(("event"))
    S -. "ArtifactDeleted" .-> E_ArtifactDeleted(("event"))

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

Domain model

Artifact — An immutable content object addressed by hash with metadata, classification, access scope, producer (run, attempt, agent), inputs it derived from and the version chain it belongs to (artifact-v1). (catalog entry)

Field	Type	Required	Description
artifactId	guid	yes
tenantId	string	yes
projectId	string	yes
kind	enum:ArtifactKind	yes
name	string	yes
contentHash	hash	yes
contentRef	string	yes	Blob reference in artifact-blob.
sizeBytes	long	yes
mediaType	string	yes
classification	string	yes
accessScope	json	yes	Who may read beyond the project scope.
producerRunId	guid	no
producerAttemptId	guid	no
producerAgentId	string	no
chainId	guid	yes	Version chain this artifact belongs to.
versionInChain	int	yes
state	enum:ArtifactState	yes
validationRef	string	no
createdAt	datetime	yes

Invariants:

• Content is immutable; a new content hash is a new artifact and a new version in its chain.
• Every artifact produced by a run records the run, attempt and agent; every derived artifact records its inputs as lineage edges.
• Deleting an artifact (D31) removes content and keeps metadata and lineage marked Deleted so that references stay explainable.

stateDiagram-v2
    Stored --> Validated : ValidationRecorded
    Stored --> Superseded : NewVersionStored
    Validated --> Superseded : NewVersionStored
    Stored --> Deleted : Delete
    Validated --> Deleted : Delete
    Superseded --> Deleted : Delete

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

Events: ArtifactStored, ArtifactValidated, ArtifactSuperseded, ArtifactDeleted · Tables: Artifacts, LineageEdges, VersionChains · Repository: ArtifactRepository

erDiagram
    Artifact {
        guid artifactId PK
        string tenantId
        string projectId
        enum_ArtifactKind kind
        string name
        hash contentHash
        string contentRef
        long sizeBytes
        string mediaType
        string classification
        json accessScope
        guid producerRunId
        guid producerAttemptId
        string producerAgentId
        guid chainId
        int versionInChain
        enum_ArtifactState state
        string validationRef
        datetime createdAt
    }
    LineageEdge {
        guid edgeId

        string inputKind

        string inputRef

        string relation

    }
    Artifact ||--o{ LineageEdge : contains

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

Entities and value objects

LineageEdge (entity, in Artifact) — A derivation edge from an input (artifact, source chunk, context snapshot) to this artifact.

Field	Type	Required	Description
edgeId	guid	yes
inputKind	string	yes	artifact
inputRef	string	yes
relation	string	yes	derived-from

Data model and storage

Store	Role	Engine / profile	Tables
Knowledge metadata store	primary	azure-sql / nhibernate-sqlserver	VersionChains, Artifacts, LineageEdges
Artifact content store	blob	blob / azure-blob	—

Table	Owner	Columns	Indexes
dbo.VersionChains	Artifact	5	1
dbo.Artifacts	Artifact	19	3
dbo.LineageEdges	LineageEdge	6	1

Full DDL: appendix.

Content lives in artifact-blob under the tenant's region with encryption at rest; metadata and lineage in knowledge-sql. Deletion removes content and keeps the metadata row marked Deleted so that lineage stays explainable; export packages are themselves artifacts of kind Export.

APIs

Method	Path	Operation	Scope	Side effects	Idempotency	Gateway	Summary
GET	/factory/artifacts/{artifactId}	GetArtifact	factory.artifacts.read	read	natural	GW-03	Metadata, lineage, version chain position and a scoped download reference.
GET	/factory/artifacts/{artifactId}/preview	PreviewArtifact	factory.artifacts.read	read	natural	GW-03	Rendered preview (diff, document, report) under the caller's scope; projection, never a second copy.
GET	/factory/artifacts/{artifactId}/versions	ListArtifactVersions	factory.artifacts.read	read	natural	GW-03	The version chain of an artifact.
GET	/factory/runs/{runId}/artifacts	ListRunArtifacts	factory.runs.read	read	natural	GW-03	Artifacts produced by a run with their validation state.
POST	/factory/projects/{projectId}/artifacts/export	ExportArtifacts	factory.artifacts.admin	external	key-header	GW-03	Export a project's artifacts, lineage and metadata in open formats (D31, XL-14).

gRPC service	Method	Streaming	Visibility	Side effects	Summary
Artifacts	Store	client	internal	shared-write	Store content by hash with metadata, producer and lineage; idempotent on tenant and hash within a chain.
Artifacts	Fetch	server	internal	read	Stream content of an artifact under scope.
Artifacts	RecordValidation	none	internal	shared-write	Attach a validator verdict to an artifact.

Messages

Event	Topic	Scope / v	Aggregate	Consumers	Summary
ArtifactStored	artifacts.artifacts.v1.artifact-stored	integration / 1	Artifact	StudioBff, DashboardService, KnowledgeIngestionService, MemoryPromotionService	Content stored with metadata and lineage.
ArtifactValidated	artifacts.artifacts.v1.artifact-validated	integration / 1	Artifact	BlueprintService, PipelineExecutionService, FeedbackService, StudioBff, QualityScoreService	A validator verdict was attached.
ArtifactSuperseded	artifacts.artifacts.v1.artifact-superseded	integration / 1	Artifact	StudioBff	A newer version exists in the chain.
ArtifactDeleted	artifacts.artifacts.v1.artifact-deleted	integration / 1	Artifact	AuditService, DashboardService	Content removed; metadata and lineage kept.

ArtifactStored payload:

Field	Type	Required	Description
artifactId	guid	yes
tenantId	string	yes
projectId	string	yes
kind	enum:ArtifactKind	yes
contentHash	hash	yes
producerRunId	guid	no
chainId	guid	yes
versionInChain	int	yes

ArtifactValidated payload:

Field	Type	Required	Description
artifactId	guid	yes
tenantId	string	yes
passed	bool	yes
validationRef	string	yes

ArtifactSuperseded payload:

Field	Type	Required	Description
artifactId	guid	yes
tenantId	string	yes
chainId	guid	yes
newArtifactId	guid	yes

ArtifactDeleted payload:

Field	Type	Required	Description
artifactId	guid	yes
tenantId	string	yes
reason	string	yes

Command	Handled by	Result events	Summary
Store	Artifact	ArtifactStored, ArtifactSuperseded
RecordValidation	Artifact	ArtifactValidated
Delete	Artifact	ArtifactDeleted

Event	Producer	Handler	Purpose
RunCompleted	RunControlService	SealRunArtifacts	Mark the run's artifacts as final outputs and close open chains.
ProjectStateChanged	ProjectService	ExportOrDeleteOnClosing	Export or delete project artifacts on Closing (XL-14).

Workers and jobs

Worker	Trigger	Output events	Retry	Idempotency key	Summary
RetentionSweeper	schedule 0 4 * * *	ArtifactDeleted	fixed	artifactId	Deletes content past the project retention window and writes deletion evidence; keeps metadata and lineage.
ExportWorker	event	ArtifactStored	exponential	projectId + exportRequestId	Produces an export package (artifacts, metadata, lineage in open formats) for a project.

Actors and grains

None modelled

No grains are modelled for this item yet.

Sagas and long-running flows

None modelled

No sagas are modelled for this item yet.

Options and configuration

Section	Key	Type	Default	Reloadable	Secret	Summary
Knowledge:Artifacts	MaxArtifactMb	int	512	yes	no	Size limit per artifact.
Knowledge:Artifacts	PreviewRenderers	string[]	[diff, markdown, json, report]	yes	no	Preview projections available.

Metrics and observability

Metric	Instrument	Unit	Dimensions	Summary
connectsoft.factory.artifacts.stored	counter	{artifact}	tenant, kind	Artifacts stored.
connectsoft.factory.artifacts.bytes	updown	By	tenant	Stored bytes per tenant (StorageGb meter).
connectsoft.factory.artifacts.deleted	counter	{artifact}	tenant, reason	Deletions by reason.

Security

Authentication	client-credentials
Scopes	factory.artifacts.read (Read artifacts in scope.); factory.artifacts.admin (Export and delete.); factory.runs.read (Artifacts of a run.)
Roles	Requester, Reviewer, AssetMaintainer, Operator, WorkspaceAdmin, PlatformAdmin, Observer
Tenant isolation	row-filter
Data classification	confidential
Max side-effect class	external
Secrets	artifact-blob (key-vault, rotate 90 d)

Dependencies

Outbound

Target	Kind	Purpose	Failure mode	Required
PolicyEngineService	grpc	Classification and redaction on store and preview.	fail-fast	yes
CostUsageService	grpc	StorageGb meter.	degrade	no
AuditService	event	Deletion and export evidence.	queue	yes

Inbound

Target	Kind	Purpose	Failure mode	Required
AgentRuntimeService	grpc	Store checkpoints, outputs and change sets.	—	yes
ModelRouterService	grpc	Store model outputs.	—	yes
KnowledgeIngestionService	grpc	Store normalized content.	—	yes
ContextBuilderService	grpc	Store plans and assembled contexts.	—	yes
StudioBff	sync-http	Artifact views, previews, exports.	—	yes

Failure and recovery

Scenario	Detection	Recovery	Data impact	RTO (min)
Blob store unavailable	Store failures	callers fail fast (an attempt cannot checkpoint without it); restore order places artifacts after the run journal and outbox	none	240
Hash collision suspected	same hash with different size	store refused with an explicit error; investigated as an incident	none	0

NFR targets

Target	Class value (pilot-interactive)	Override
latency_p95_ms	2000	—
availability_pct	99.5	—
throughput_rps	50	—
rpo_minutes	15	—
rto_minutes	240	—
cost_class	low	—

Deployment

Granularity	module of host · host KnowledgeHost
Topologies	saas-default, hybrid, on-prem, hybrid-compute
Runtime	—; replicas —–—
Ports	—

Current implementation

ConnectSoft.Extensions.DataStorage.Abstractions and its file-system provider exist as the storage port; no artifact registry, lineage or version chain exists.

Later capabilities

Semantic (not textual) diff between artifact versions; content-addressed deduplication across tenants where classification allows; signed artifacts for release manifests and evaluation records.

Decisions and traceability

Family	Ids
FR	FR-08
FUX	FUX-06
NFR	NFR-03, NFR-05, NFR-16
XL	XL-06, XL-14

Related

• Knowledge governance · Data governance · AgentRegistryService · Shared contracts

• Knowledge Platform microservices · bounded contexts · APIs · events · data model

• Services catalog · Ownership map