AIFACTORY-FEAT-176: Audit library: the Factory audit evidence record and its sink¶
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 Ecosystem component extensions · Increment I1 Generate a microservice · State elaborated · Route backend-developer · Phase before development · Build order 22 of 185 (Templates and libraries)
Before development
Template or library work: every task of this feature changes a template or a shared library the Factory builds on, and it lands before the Factory's own repositories of I1 are developed. The mark travels with every task (tag phase:before-development).
Eleven Factory services depend on the Audit.NET integration library for audit evidence, and ADR-0019 keeps that evidence seven years, redacted and immutable. The library records generic audit events; the Factory needs the record shape of audit-evidence.schema.json (scope, run, step, the kind of actor, an evidence reference), generated from the contracts package rather than typed in each service, and a sink that carries the records to the Audit service under the accepted envelope with a durable fallback. Component: Audit.NET integration (extend).
| Delivers | — |
| Stubs | — |
| Realizes | components: cmp-audit adrs: ADR-0019, ADR-0021 |
| Requirements | — |
| Depends on | AIFACTORY-FEAT-090 Contracts package from the published schemas |
| Sources | model/components.yaml, docs/reference/schemas/audit-evidence.schema.json, docs/architecture/adr/0019-data-governance.md |
AIFACTORY-US-261: Audit library: an audit scope yields the evidence record of audit-evidence-v1 from the contracts package, with tenant and actor from the trusted scope, and a record without a tenant is refused¶
enabling · persona platform-admin
As a platform admin, I want every Factory service to build its audit evidence from one record type and one builder, so that evidence from eleven services has the same shape and none of them types a field of its own.
The Features page of the Audit.NET integration library lists what the library configures: the options AuditNetOptions, two data providers selected by AuditDataProviderType, SQL Server and file system, and the registration AddConnectSoftAuditNet. The events it records are the generic events of Audit.NET, JSON documents with an event type, a target type and durations. Eleven Factory services name the library for audit evidence, and the shape of that evidence is fixed by docs/reference/schemas/audit-evidence.schema.json: an evidence identifier, the tenant and optionally the project, the time, an actor with an identifier and one of the kinds user, workload, partner-agent and system, one action of a closed list, a subject with kind, identifier and hash, an outcome, a redacted reason, the policy decision, a correlation with run, approval and event identifiers, and the list of redacted fields. The feature text and model/components.yaml also name a step and an evidence reference. The schema has no field for a step: its correlation holds runId, approvalId and eventId and admits no additional property, so the record carries no step; the evidence reference of the feature text is the evidence identifier together with the hash of the subject. This PBI adds the Factory evidence mapping to the library. The record type is the one the contracts package generates from the schema; the library pins that package and types no field of its own. A builder turns an audit scope into the record: tenant and project come from the scope accessor of ConnectSoft.Extensions.AI.Factory.Abstractions, the actor identifier, kind, roles and delegation from the validated token, the run of the correlation from the scope while a run is in flight, and the action, the subject and the outcome from the caller. A workload token carries service scopes and no tenant claim, so for a workload actor the tenant is the one the workload forwards and the scope accessor admits. The builder refuses a record without a tenant, an action outside the list and a subject without an identifier with a typed error that names the field, and writes nothing. It accepts no prompt text, payload or secret value, which the invariant of AuditEntry in model/services/governance/AuditService.yaml forbids: a caller passes the hash of the object acted upon. The chain hash is no part of what a service submits: the library never sets it, because only the Audit service knows the previous record of the tenant, and the Audit service computes the hash when its command SubmitEvidence appends the record.
Acceptance criteria
| AC1 | Given a host with a scope established and a validated user token, when a command completes inside an audit scope with an action, a subject and an outcome, then the builder yields a record of audit-evidence-v1 whose tenant and project equal the scope, whose actor carries the identifier, the kind user, the roles and the delegation of the token, and whose correlation carries the run of the scope (ADR-0019 decision 3, docs/reference/schemas/audit-evidence.schema.json). |
| AC2 | Given a call under a workload token, which carries service scopes and no tenant claim, when the builder runs, then the actor kind is workload and the tenant is the one the workload forwarded and the scope accessor admitted; given a background loop without a caller, then the actor kind is system and the tenant is the tenant of the work item (ADR-0015 decision 2 and its amendment on workload tokens). |
| AC3 | Given no scope is established, an action outside the closed list or a subject without an identifier, when the builder runs, then it refuses with a typed error that names the field and no record is written; the actions of the list include the publications and approval decisions that ADR-0021 has recorded, and a free text reason is never taken as content (ADR-0019 decision 3). |
| AC4 | Given the record type of the library, when the contract test runs against the pinned contracts package, then the library defines no evidence type of its own and the serialised record validates against the schema of audit-evidence-v1 in every field except the chain hash, which is no part of a submitted record and is computed by the Audit service when it appends the record (model/services/governance/AuditService.yaml). |
| Traces: services | AuditService |
| Traces: descriptors | audit-evidence-v1, execution-scope-v1 |
| Traces: adrs | ADR-0015, ADR-0019, ADR-0021 |
| Relates: nfrs | NFR-04 |
| Depends on | feature:contracts-package, feature:component-extensions-ai |
| Sources | model/components.yaml, model/services/governance/AuditService.yaml, docs/reference/schemas/audit-evidence.schema.json, docs/architecture/adr/0019-data-governance.md, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1192 Evidence builder contract over the record type of the contracts package |
contract | The library exposes one builder interface that takes an action, a subject with its hash, an outcome and an optional reason and policy decision and returns the evidence record type of the pinned contracts package; a contract test proves that the library declares no evidence type and that the record validates against docs/reference/schemas/audit-evidence.schema.json apart from the chain hash. | ConnectSoft.Extensions.AuditNet |
AIFACTORY-TASK-635 Factory audit record shape |
implementation | The builder fills tenant and project from the scope accessor, the actor identifier, kind (user, workload, partner-agent or system), roles and delegation from the validated token, and the run of the correlation from the scope, per audit-evidence.schema.json and with the record type generated in the contracts package, with a test that a record without a tenant is refused. | ConnectSoft.Extensions.AuditNet |
AIFACTORY-TASK-1193 Refusal tests of the evidence builder |
fixture | A test fixture builds evidence under a user token, a workload token and a background loop, and plants a missing scope, an action outside the list, a subject without an identifier and a content value passed as a reason; each planted case is refused with the field named and writes nothing. | ConnectSoft.Extensions.AuditNet |
AIFACTORY-TASK-1194 Verify the evidence record against the schema and the refusals |
verification | Run dotnet test -c Release --no-build on the library solution; the builder tests for the three actor kinds, the schema validation test and the refusal tests pass and prove AC1 to AC4 of AIFACTORY-US-261 (ADR-0019, docs/reference/schemas/audit-evidence.schema.json). |
ConnectSoft.Extensions.AuditNet |
AIFACTORY-US-262: Audit library: a sink publishes each evidence record under the run event envelope through the messaging port, in the transaction of the command, with a durable local fallback¶
enabling · persona platform-admin
As a platform admin, I want the evidence of a command to travel to the Audit service with the state change that caused it, so that a committed command cannot lose its evidence and a rolled back command leaves none.
The library writes audit events to SQL Server or to files in the service that raised them. Factory evidence belongs to the Audit service, which appends it to the hash chain of the tenant and mirrors it to the immutable store (model/services/governance/AuditService.yaml). This PBI adds a third data provider beside the two of AuditDataProviderType: the Factory sink. The sink redacts the record with the audit profile of the Compliance library, which the feature component-compliance-factory-classifications delivers, and lists the removed fields in redactions. It wraps the record as the payload of the run event envelope of the contracts package, with tenant, project, run and correlation from the scope and the classification restricted, the class docs/architecture/data-governance.md assigns to audit evidence, and hands it to the messaging port. The evidence event travels on the topic audit.evidence.v1.evidence-submitted. Its event type name and that topic are constants of the pinned contracts package, where every Factory event type is declared; the library declares neither, and a golden file fixes the envelope and the payload without chainHash, which the Audit service computes and a service never submits. AgentEventEnvelope is not used here: the amendment of ADR-0014 on envelopes per event family keeps it for agent lifecycle events. The path of the evidence is decided (D115): evidence travels as an event that a service writes to its outbox in the transaction of its command, because only an outbox record can commit with the state change of the command. model/services/governance/AuditService.yaml gives the Audit service the command SubmitEvidence for that event, handled by AuditEntry: the record is appended once per evidence identifier by the same append Audit.Record performs, and the gRPC operation Audit.Record stays for commands that are not events, so both end in one record of the chain. When a unit of work is open, the outbox record of the evidence is committed with the state change of the command, as ADR-0014 decision 4 requires, so a rolled back command leaves no evidence and a committed command cannot lose it. When the port cannot take the record, because no unit of work is open or the store of the outbox refuses, the sink appends the redacted record to the durable local provider the library already has, SQL Server or file system, and a forwarder hands the stored records to the port in their order when it accepts again. A record is never dropped and never written unredacted. A record whose redaction fails is refused with the field named and counted on a metric without its value. The event identifier of the envelope is the evidence identifier, so a record forwarded twice is one record for the Audit service. The sink references the messaging port and no transport.
Acceptance criteria
| AC1 | Given a command that changes state inside a unit of work and completes an audit scope, when the unit of work commits, then the outbox holds one event of the evidence event type, on the topic audit.evidence.v1.evidence-submitted that the pinned contracts package names, under run-event-envelope-v1, whose payload is the evidence record without chainHash, whose tenant, project, run and correlation equal the scope, whose classification is restricted and whose event identifier is the evidence identifier, and the serialised event matches its golden file; when the unit of work rolls back, then no outbox record and no evidence exists (ADR-0014 decision 4, docs/architecture/data-governance.md). |
| AC2 | Given the messaging port cannot take a record, when an audit scope completes, then the redacted record is appended to the durable local provider and the command is not failed by the sink; when the port accepts again, then the forwarder publishes the stored records in their order and a record published twice carries the same event identifier, so that the command SubmitEvidence of the Audit service appends it once per evidence identifier (ADR-0014 decision 3, model/services/governance/AuditService.yaml). |
| AC3 | Given a record with a field the audit profile redacts, when the sink writes it to the port or to the local provider, then the field is replaced before the write and named in redactions; given a record whose redaction fails, then the sink refuses it with the field named, counts the refusal and writes the value nowhere (ADR-0019 decisions 2 and 3). |
| AC4 | Given the sink assembly, when the architecture test of the library runs, then it references the messaging port and the run event envelope of the pinned contracts package and no transport client, and it does not reference AgentEventEnvelope (ADR-0012 decision on the messaging port, ADR-0014 amendment on envelopes per event family). |
| Traces: services | AuditService |
| Traces: descriptors | audit-evidence-v1, run-event-envelope-v1 |
| Traces: adrs | ADR-0012, ADR-0014, ADR-0019 |
| Relates: nfrs | NFR-04 |
| Depends on | AIFACTORY-US-261, feature:contracts-package, feature:component-compliance-factory-classifications |
| Sources | model/components.yaml, model/services/governance/AuditService.yaml, docs/architecture/data-governance.md, docs/architecture/adr/0014-run-and-lifecycle-envelopes.md, docs/architecture/adr/0012-messaging-port-and-transport-profiles.md, docs/reference/schemas/run-event-envelope.schema.json |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1291 Evidence event type, its topic constant and the golden file of the envelope |
contract | The sink takes the event type name and the topic constant of the evidence event, audit.evidence.v1.evidence-submitted, from the pinned contracts package and declares neither; a golden JSON file fixes the run event envelope with the evidence record as its payload and without chainHash; a contract test fails when the serialised event differs from the file or when the library declares an event type or a topic of its own; the Features page states that the command SubmitEvidence of the Audit service appends the event once per evidence identifier by the same append as Audit.Record, which stays for commands that are not events (model/services/governance/AuditService.yaml). |
ConnectSoft.Extensions.AuditNet |
AIFACTORY-TASK-636 Audit sink to the Audit service under the envelope |
implementation | A third data provider of the library publishes each evidence record through the messaging port, as the evidence event type and on the topic audit.evidence.v1.evidence-submitted of the pinned contracts package, under the run event envelope of that package to the Audit service, enlisted in the open unit of work so that the outbox record commits with the state change, with redaction by the audit profile of the Compliance library before the write and the evidence identifier as the event identifier. |
ConnectSoft.Extensions.AuditNet |
AIFACTORY-TASK-1195 Durable local fallback and its ordered forwarder |
implementation | When the port cannot take a record the sink appends the redacted record to the SQL Server or file system provider of the library, and a hosted forwarder hands the stored records to the port in their order when it accepts again and removes each only after the port took it; the options of AuditNetOptions select the fallback provider and are validated at start. |
ConnectSoft.Extensions.AuditNet |
AIFACTORY-TASK-1196 Commit, rollback, outage and failed redaction tests of the sink |
fixture | A test fixture with an in-memory messaging port and a real unit of work proves the committed and the rolled back command, an outage of the port with ordered forwarding and a duplicate forward, and a record whose redaction fails; an architecture test asserts that the sink references no transport client and no AgentEventEnvelope. |
ConnectSoft.Extensions.AuditNet |
AIFACTORY-TASK-1197 Verify the sink on commit, rollback, outage and redaction |
verification | Run dotnet test -c Release --no-build on the library solution; the golden file test of the evidence event, the commit, rollback, outage, duplicate and failed redaction tests and the architecture test pass and prove AC1 to AC4 of AIFACTORY-US-262 (ADR-0014, ADR-0019). |
ConnectSoft.Extensions.AuditNet |
AIFACTORY-US-263: Audit library: the package with the evidence record and the sink is built, tested and published to the ConnectSoft feed with a version its consumers pin¶
evidence · persona platform-admin
As a platform admin, I want the audit package with the Factory evidence on the feed under a version a service can pin, so that the services of this increment record evidence through a published package and not through a local build.
This PBI is the publication proof of the feature. The Overview page of the library names packaging and deployment through Azure DevOps among what the repository provides, and the epic is done only when each library publishes before the Factory code that consumes it is built (model/backlog/epics.yaml). The pipeline of the repository builds the library, runs its tests, packs and pushes the package to the ConnectSoft feed, the Azure Artifacts feed the ConnectSoft libraries already publish to. The contracts package, the abstractions package and the Compliance package are restored from that feed at their published versions and never from a project reference. Publication is reached only when the tests pass and refuses a version that is already on the feed. A probe then proves the package from the side of a consumer: a clean host that takes every ConnectSoft package from the feed registers AddConnectSoftAuditNet with the Factory sink, establishes a scope, completes one audit scope inside a unit of work and finds one evidence event under the run event envelope in an in-memory messaging port, with the tenant of the scope and the field of a planted secret named in its redactions. The published version is recorded on the Runbook page of the library, where the eleven consuming services read their pin. This is an evidence PBI (D113): a library feature has no scenario, so the probe names what it proves through its ADRs, the requirement on release gates and its sources.
Acceptance criteria
| AC1 | Given the pipeline of the library repository after the work of the feature, when it runs, then the package is built, tested, packed and pushed to the ConnectSoft feed, the contracts, abstractions and Compliance packages are restored from the feed at their published versions, and the published version is recorded on the Runbook page (FR-11, ADR-0028, model/backlog/epics.yaml). |
| AC2 | Given a clean probe host that restores every ConnectSoft package from the feed and holds no project reference, when it completes one audit scope inside a unit of work under an established scope, then its in-memory messaging port holds one evidence event under the run event envelope with the tenant of the scope, and a planted secret value appears nowhere in the event while its field is named in the redactions (ADR-0014 decision 4, ADR-0019 decision 3). |
| AC3 | Given a failing test or a version that is already on the feed, when the pipeline reaches the publication stage, then the stage is refused with the reason and nothing is pushed; a run with a planted failing test proves the refusal (FR-11, docs/architecture/ecosystem-composition.md). |
| Traces: adrs | ADR-0014, ADR-0019, ADR-0028 |
| Traces: requirements | FR-11 |
| Depends on | AIFACTORY-US-261, AIFACTORY-US-262 |
| Sources | model/components.yaml, model/backlog/epics.yaml, docs/architecture/ecosystem-composition.md, docs/architecture/catalogs/libraries.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1198 Version guard and feed restore in the audit library pipeline |
operations | The pipeline of the repository restores the contracts, abstractions and Compliance packages from the ConnectSoft feed, publishes the package only after the tests of the solution pass and refuses a version that is already on the feed with the reason. | ConnectSoft.Extensions.AuditNet |
AIFACTORY-TASK-1199 Feed probe host for the published audit package |
fixture | A probe project that restores every ConnectSoft package from the feed and holds no project reference registers the Factory sink with an in-memory messaging port, completes one audit scope with a planted secret inside a unit of work and asserts on the evidence event; the probe runs as the last stage of the pipeline. | ConnectSoft.Extensions.AuditNet |
AIFACTORY-TASK-1200 Published version and the Factory provider recorded on the library pages |
documentation | The Runbook page of the library names the published version and the versions of the contracts, abstractions and Compliance packages it pins, and the Features and Getting Started pages describe the evidence builder, the Factory sink as the third data provider and its fallback. | ConnectSoft.Extensions.AuditNet |
AIFACTORY-TASK-1201 Verify the published audit package by the probe and by a planted failing run |
verification | One run of the pipeline publishes the package and the probe passes; one run with a planted failing test stops before publication; both runs prove AC1 to AC3 of AIFACTORY-US-263 (FR-11, ADR-0028). | ConnectSoft.Extensions.AuditNet |
AIFACTORY-US-116: Audit library: the Factory audit evidence record and its sink is delivered and proven by its consumers¶
enabling · persona platform-admin
As a platform admin, I want Audit.NET integration to carry the Factory audit evidence record and its sink, so that it serves audit evidence without later rework.
This is the integration PBI of the feature. With the evidence builder, the Factory sink and the publication proof of the earlier PBIs, a Factory service records audit evidence by three steps and no code of its own: it pins the published ConnectSoft.Extensions.AuditNet package, registers AddConnectSoftAuditNet with the Factory sink, and completes an audit scope with an action, a subject and an outcome inside the unit of work of its command. The record has the shape of the contracts package, its tenant and actor come from the trusted scope, it is redacted by the audit profile of the Compliance library, and it leaves the service under the run event envelope together with the state change. A record without a tenant is refused, a rolled back command leaves no evidence, and an outage of the port delays evidence in a durable local store without losing or reordering it. ADR-0019 keeps this evidence seven years, redacted and immutable; the library delivers the redacted record and its transport, and the Audit service keeps the chain. The implementation lives in the tasks of the earlier PBIs; this PBI keeps the migrated verification of the feature. The feature is done when the package is on the ConnectSoft feed with the version the Runbook page names and the probe host proves it from the feed.
Acceptance criteria
| AC1 | Given the library repository ConnectSoft.Extensions.AuditNet with the work of this feature, when its pipeline runs, then the package builds, its tests pass and it publishes to the ConnectSoft feed with a verified version that the consuming repositories pin (ADR-0019, model/components.yaml). |
| AC2 | Given the work of AIFACTORY-TASK-635 (factory audit record shape) is done, then the evidence record carries tenant and project from the scope, the actor with its kind, the action, the subject with its hash, the outcome and the correlation with the run per docs/reference/schemas/audit-evidence.schema.json, with the record type generated in the contracts package and a test that a record without a tenant is refused; the step of the migrated text is not carried because the schema has no field for it, and its evidence reference is the evidence identifier with the hash of the subject (ADR-0019 decision 3, ADR-0021). |
| AC3 | Given the work of AIFACTORY-TASK-636 (audit sink to the Audit service under the envelope) is done, then the sink publishes evidence through the messaging port under the run event envelope in the transaction of the command, with a durable local fallback when the port cannot take the record and redaction by the Compliance library before the write (ADR-0019 decision 2, model/services/governance/AuditService.yaml). |
| Traces: services | AuditService |
| Traces: adrs | ADR-0019, ADR-0021 |
| Depends on | AIFACTORY-US-261, AIFACTORY-US-262, AIFACTORY-US-263 |
| Sources | model/components.yaml, model/services/governance/AuditService.yaml, docs/reference/schemas/audit-evidence.schema.json, docs/architecture/adr/0019-data-governance.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1202 Use case page for recording Factory evidence from a service |
documentation | The Use Cases page of the library holds one worked case of a Factory service: the registration with the Factory sink, an audit scope around a command inside its unit of work, the resulting evidence event and what the service sees on a refusal and on an outage of the port. | ConnectSoft.Extensions.AuditNet |
AIFACTORY-TASK-670 Verify audit-factory-evidence-delivered by running the declared command |
verification | Run dotnet build -c Release and dotnet test -c Release --no-build on the library solution and the probe host of AIFACTORY-TASK-1199 against the published version; they pass and prove AC1 to AC3 of AIFACTORY-US-116. |
ConnectSoft.Extensions.AuditNet |