AIFACTORY-FEAT-064: AuditService: 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 Governance (PF-12) · Increment I1 Generate a microservice · State elaborated · Route backend-developer · Build order 77 of 185 (Factory code)
AuditService is the service of bounded context BC-19 (Audit). Append-only audit evidence with a hash chain in the immutable store for every command, decision, approval, publication, credential issuance and effect; the data classification registry with retention and redaction rules that other services obey; findings and exports for tenants and auditors (BC-19, audit-evidence-v1, D31). It is delivered complete in the first outcome by owner decision (D80), so that every run is audited from its first command. Its own repository is ConnectSoft.AI.SoftwareFactory.AuditService.
| Delivers | AuditService (complete) |
| Stubs | — |
| Realizes | adrs: ADR-0014, ADR-0019 |
| Requirements | FR-06, FR-08, FUX-05, FUX-06, NFR-03, NFR-04, NFR-10, XL-05, XL-13, XL-14 |
| Depends on | — |
| Sources | model/services/governance/AuditService.yaml |
Scenarios to trace (15, catalog): SCN-AuditService-001 ✓, SCN-AuditService-002 ✓, SCN-AuditService-003 ✓, SCN-AuditService-004 ✓, SCN-AuditService-005 ✓, SCN-AuditService-006 ✓, SCN-AuditService-007 ✓, SCN-AuditService-008 ✓, SCN-AuditService-009 ✓, SCN-AuditService-015 ✓, SCN-AuditService-010 ✓, SCN-AuditService-011 ✓, SCN-AuditService-012 ✓, SCN-AuditService-013 ✓, SCN-AuditService-014 ✓
AIFACTORY-US-019: Every run leaves verifiable audit evidence¶
behavior · persona observer
As an observer, I want every command, decision, approval and effect of a run recorded as append-only evidence with a chain I can verify, so that I can show afterwards who did what, under which authority, and that nothing was altered.
This is the integration PBI of the feature: it proves on a deployed instance that AuditService turns what the Factory does into evidence that can be verified. AuditService is the authoritative writer of bounded context BC-19 and is delivered complete in the first outcome by owner decision D80, so that every run is audited from its first command. Evidence reaches it on three paths that end in one append. A Factory service writes an audit-evidence-v1 record to its own outbox in the transaction of its command, and the record arrives as the event AuditEvidenceSubmitted on audit.evidence.v1.evidence-submitted, where the command SubmitEvidence appends it once per evidence identifier (D115). The integration events the model lists under the consumed events of the service are recorded as evidence by RecordEvidence. And Audit.Record appends evidence of a command that is not an event. Every entry takes the next sequence of its tenant and the hash of its predecessor, is mirrored to the immutable store, and the head of each tenant chain is verified and signed daily with a key that stays in Azure Key Vault. In this increment the callers are services, not people. 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 AIFACTORY-US-961 to AIFACTORY-US-970 prove is not proven again here. Producers of the fixture, shaped like RunControlService, PolicyEngineService, ToolAdapterService and SecretBrokerService and built from the pinned contracts package, publish on the deployed transport the events of five acts of one run: its submission, a policy decision, an approval decision, a tool invocation and a credential issuance. The submission of a run is audited through RunAccepted of RunControlService, which RecordEvidence appends as the evidence of the submission (D126, D135). The issuance arrives once, as the event CredentialIssued, which names the policy decision that allowed it: it leaves exactly one audit entry, and SecretBrokerService submits no evidence record of its own for it (D126, D135). The SubmitEvidence path is proven with one audit-evidence-v1 record of the closed action list for an act no consumed event announces, the action break-glass, which a producer shaped like RunControlService submits on the evidence topic. The suite then reads the trail of the run through SearchAudit, verifies the chain positions it returns, waits for a run of ChainVerifier and checks the signed head against the key of the vault of the environment. No dependency of the feature delivers an on-demand trigger of a scheduled worker, and ADR-0015 reserves worker triggers for the Platform admin, so the suite triggers nothing: the acceptance deployment sets the schedule of the worker through the configuration of the instance, Governance:Audit:ChainVerifierSchedule (AIFACTORY-US-962), so that a run falls inside the suite, and the fixture tenant is new for every run of the suite, because the worker runs once per tenant and day. That a run of the real chain leaves an entry for each of these acts is proven where the real services run together, by the outcome verification of the increment (feature verify-generate-a-microservice); this PBI proves that the deployed Audit service records, chains, verifies and returns them. The suite reads through the REST route of the deployed instance with an Observer token whose audience is the one of the Governance gateway, issued by the authorization server of the acceptance environment. A person reaches that route through GovernanceHost, which fronts the service from I1 (D127), and this feature builds no direct public route. The audit commands of the command-line client, which search the trail of a run and request an export, are written against the client port and reach the deployed service through the Governance gateway with a token of its audience, because the token of the client for the control plane gateway has that one audience and the Governance gateway needs a token of its own; the suite proves them against a fake of the gateway routes, and the acceptance stage of the increment calls them against the deployed gateway.
Acceptance criteria
| AC1 | Given the container image that the pipeline of the repository published (AIFACTORY-US-961), deployed in the acceptance environment with its secret references audit-chain-key and messaging-transport, when the instance starts against audit-sql, audit-immutable, the Key Vault, the identity authority and the deployed ArtifactService of that environment, the required dependency that readiness names by AIFACTORY-US-963, 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-961, AIFACTORY-US-962 and AIFACTORY-US-963 and are not proven again here (ADR-0019, model/services/governance/AuditService.yaml). |
| AC2 | Given the fixture producers publish for one run the events RunControlService/RunAccepted, PolicyEngineService/PolicyDecisionRecorded, RunControlService/ApprovalDecided, ToolAdapterService/ToolInvoked and SecretBrokerService/CredentialIssued and one audit-evidence-v1 record with the action break-glass of the closed list of docs/reference/schemas/audit-evidence.schema.json as AuditEvidenceSubmitted on the deployed transport, when AuditService/SearchAudit is called for the run, then it returns one AuditService/AuditEntry per delivery, six in all, the submission of the run from RunAccepted and the issuance exactly once from its event with the policy decision it names, each with tenant, project, run and actor and with consecutive sequences of the tenant, each entry hash follows from its record and the hash of its predecessor, and the subscriber of the fixture received exactly one AuditService/AuditEntryRecorded per entry in the run event envelope (ADR-0014). |
| AC3 | Given the entries of AC2 and an acceptance deployment whose configuration sets Governance:Audit:ChainVerifierSchedule so that a run of ChainVerifier falls inside the suite, when the suite waits for that run and triggers nothing itself, then AuditService/AuditChainVerified is received with valid true and the sequence of the last entry of the fixture tenant as head sequence, one verification entry follows that head in the trail, and the signature of the head verifies with the public part of the key the vault of the environment holds, a key that never left the vault (docs/planes/trust-operations/governance/security.md). |
| AC4 | Given the entries of AC2 on the deployed instance and tokens issued by the authorization server of the acceptance environment, when an Observer of another tenant searches for the run over the real route, a workload with the service scope appends one record through AuditService/Audit.Record over the real channel, and the events and the record of AC2 are delivered again on the deployed transport after a restart of the instance, then the search returns an empty page, the appended record is in the trail of its tenant, no second entry exists for a redelivered event or record, every entry and the signed head stand as before the restart and the sequence of the tenant continues without a gap, and a scan of the entries, the log records, the activities and the metrics of the instance for the marker text of the fixture finds it in none; the isolation rules are owned by AC1 of AIFACTORY-US-963 and the deduplication and the refusals of the three paths by AC1 to AC3 of AIFACTORY-US-964, and none is enumerated again here (ADR-0015, ADR-0019). |
| AC5 | Given the command-line client and a fake of the gateway routes of AuditService/SearchAudit and AuditService/ExportAudit, when the audit commands search the trail of a run and request an export of a project, then each sends the modelled request with the token of the Governance gateway audience, the export with an Idempotency-Key, prints the entries with their chain positions or the export request, exits with a non-zero code on 403 and 404, and no command addresses the service without the gateway (ADR-0028). |
| Traces: services | AuditService, PolicyEngineService, RunControlService, ToolAdapterService, SecretBrokerService |
| Traces: aggregates | AuditService/AuditEntry |
| Traces: apis | AuditService/SearchAudit, AuditService/ExportAudit, AuditService/Audit.Record |
| Traces: events | AuditService/AuditEntryRecorded, AuditService/AuditChainVerified, RunControlService/RunAccepted, PolicyEngineService/PolicyDecisionRecorded, RunControlService/ApprovalDecided, ToolAdapterService/ToolInvoked, SecretBrokerService/CredentialIssued |
| Traces: descriptors | audit-evidence-v1, run-event-envelope-v1 |
| Traces: adrs | ADR-0014, ADR-0015, ADR-0019, ADR-0028 |
| Traces: requirements | FR-06, NFR-04, NFR-10 |
| Relates: nfrs | NFR-04 |
| Depends on | AIFACTORY-US-961, AIFACTORY-US-962, AIFACTORY-US-963, AIFACTORY-US-964, AIFACTORY-US-965, AIFACTORY-US-966, AIFACTORY-US-967, AIFACTORY-US-968, AIFACTORY-US-969, AIFACTORY-US-970, feature:component-base-template-factory-profile, feature:component-base-template-findings, feature:contracts-package, feature:policy-engine-service, feature:run-control-service, feature:tool-adapter-service, feature:secret-broker-service, feature:artifact-service |
| Sources | model/services/governance/AuditService.yaml, model/backlog/features/governance.yaml, docs/planes/trust-operations/governance/services/audit-service/index.md, docs/planes/trust-operations/governance/security.md#evidence-integrity, docs/reference/schemas/audit-evidence.schema.json, docs/architecture/adr/0019-data-governance.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-3855 Hand-over fixture of the first outcome for the deployed audit service |
fixture | The acceptance suite holds producers shaped like RunControlService, PolicyEngineService, ToolAdapterService and SecretBrokerService that publish on the deployed transport, built from the pinned contracts package, the events RunAccepted, PolicyDecisionRecorded, ApprovalDecided, ToolInvoked and CredentialIssued of one run and one audit-evidence-v1 submission with the action break-glass as AuditEvidenceSubmitted, each with a marker text in a member that must not be stored, and that can deliver each a second time; a fixture tenant that is new for every run of the suite, an Observer user token of that tenant and one of another tenant with the audience of the Governance gateway and the scope factory.audit.read from the authorization server of the environment, a workload identity with the service scope naming AuditService and a token of that authorization server, the deployed ArtifactService of the acceptance environment as the required dependency of readiness, a subscriber on the five topics of the audit profile that records every delivered envelope, the deployment configuration that sets Governance:Audit:ChainVerifierSchedule so that a run of ChainVerifier falls inside the suite and a wait for AuditChainVerified of the fixture tenant, with no trigger of a worker by the suite, a check of the head signature against the public part of the key in the vault of the environment, a step that restarts the deployed instance and waits for its readiness, and a scan for the marker text, so that AC2 to AC4 of AIFACTORY-US-019 run against the deployed service without the four real producers. | ConnectSoft.AI.SoftwareFactory.AuditService |
AIFACTORY-TASK-309 Audit commands in the command-line client |
implementation | The client searches the trail of a run through the gateway route of SearchAudit and requests an export of a project through the gateway route of ExportAudit with an Idempotency-Key generated once and reused on a retry, prints the entries with sequence, kind, actor, action, outcome and chain position or the export request identifier, and exits with a non-zero code on 403 and 404; both commands go through the client port, ask for a token of the Governance gateway audience, because a user token has one audience, and address no service directly; GovernanceHost fronts the service from I1 (D127), so the commands are proven against a fake of the two gateway routes in the repository suite and reach the deployed gateway in the acceptance stage of the increment. | ConnectSoft.AI.SoftwareFactory.Cli |
AIFACTORY-TASK-3856 Verify the audit commands of the command-line client against a fake of the gateway |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Feature=AuditCommands" in ConnectSoft.AI.SoftwareFactory.Cli; a zero-match filter counts as a failure; the tests prove AC5 of AIFACTORY-US-019 against a fake of the gateway routes of AuditService/SearchAudit and AuditService/ExportAudit: the modelled request of each command, the token of the Governance gateway audience, the Idempotency-Key of an export reused on a retry, the printed entries and export request, and a non-zero exit code on 403 and 404. |
ConnectSoft.AI.SoftwareFactory.Cli |
AIFACTORY-TASK-753 Verify run-is-audited 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=AuditHandOver" 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 AC4 of AIFACTORY-US-019, that is the readiness of the deployed image with the deployed ArtifactService, one chained entry per delivery of the fixture run returned by AuditService/SearchAudit, the submission of the run from RunAccepted, the issuance exactly once from CredentialIssued and the break-glass record through SubmitEvidence, one AuditEntryRecorded per entry, the scheduled verification with a head signature that verifies against the vault of the environment and its verification entry, the empty search of another tenant over the real route, the record appended over the real channel, no second entry after redelivery and restart, and the scan for the marker text; the fifteen scenarios SCN-AuditService-001 to SCN-AuditService-015 are proven by the suites of AIFACTORY-US-964 to AIFACTORY-US-970 and AIFACTORY-US-1516. |
ConnectSoft.AI.SoftwareFactory.AuditService |
AIFACTORY-US-961: AuditService repository: scaffolded from the base template with the Factory profile, with the AuditEntry, ClassificationLabel and Finding aggregates and the stores audit-sql and audit-immutable¶
enabling
AuditService has its own repository, ConnectSoft.AI.SoftwareFactory.AuditService, its own deployable and its own stores (ADR-0028). The repository is created and scaffolded in I0 by AIFACTORY-TASK-231 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.AuditService --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 audit, 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, the event types and the two shapes of audit-evidence-v1, the submitted one and the stored one. On that scaffold this PBI builds the domain model and the stores and delivers no behaviour of an operation. The aggregate AuditEntry holds the seventeen fields of the model, from entryId, tenantId, the optional projectId, sequence and kind over actor, action, target, the optional reason, outcome, correlationId, the optional causationId and runId and sourceEvent to previousHash, entryHash and recordedAt, with the enum EvidenceKind and its nine families. It is append-only: the aggregate has no operation that changes or removes an entry, with the one exception the invariant of the model names, the redaction of a personal identifier after the retention window, which leaves every hashed member as it was (AIFACTORY-US-969). The aggregate ClassificationLabel holds labelId, tenantId, resourceType, the optional resourceId, which is empty for the default of a type, dataClass, retentionDays, redactionRuleIds, residency, setBy and setAt, with the entity RedactionRule (rule identifier, detector, action, the projections it applies to) and the enum DataClass, ordered Public, Internal, Confidential, Restricted; it refuses an instance label weaker than the default of its type. The aggregate Finding holds findingId, tenantId, severity, category, evidenceEntryIds, the optional owner, state, raisedAt and the optional resolvedAt, with the enum FindingSeverity. The model names four values of state, open, acknowledged, resolved and accepted-risk, and lists no transition table. A finding is raised open with at least one evidence entry, and it ends resolved or accepted-risk with resolvedAt; nothing leaves those two. The model has no operation that acknowledges a finding or sets its owner, so this delivery reaches open, resolved and accepted-risk only, keeps the fourth value in the type and reports the gap to the owner. The store audit-sql receives the five tables of the model, AuditEntries, ChainHeads, Classifications, RedactionRules and Findings, with their columns, the unique indexes UX_Audit_Tenant_Sequence and UX_Classifications_Resource and the indexes IX_Audit_Run, IX_Audit_Tenant_RecordedAt and IX_Findings_Tenant_State, under the tenant row filter of the profile. The key of RedactionRules is a correction of the model on which this PBI is built and which is reported to the owner. The model keys the table by RuleId alone with TenantId as a plain column, while each tenant names its rules itself: a second tenant that uses an identifier another tenant already holds cannot see that row under the tenant row filter, and its insert would fail on the primary key, an error that confirms a resource of another tenant (ADR-0015 amendment D113). The primary key is therefore TenantId and RuleId. The correction belongs in model/services/governance/AuditService.yaml, from which the data definition page of the service is generated; until that page is regenerated from the corrected model, this PBI cites it for columns and indexes only and states the key here. The store audit-immutable, the write-once blob store of the model, receives its container with the write-once policy; what is written to it is delivered by AIFACTORY-US-964. No table has a column for prompt text, a payload or a secret value, as the invariant of AuditEntry requires.
Acceptance criteria
| AC1 | Given the repository created and scaffolded in I0 by AIFACTORY-TASK-231 of feature repository-and-pipeline-conventions, whose first commit is the unchanged output of dotnet new connectsoft-base -n ConnectSoft.AI.SoftwareFactory.AuditService --UseFactoryProfile true from the template package at its published version with the messaging service name audit, 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 AuditService/AuditEntry, when an entry was created, then no operation of the aggregate changes sequence, kind, action, target, outcome, previousHash or entryHash or removes the entry, and the only change it admits is the redaction of a personal identifier of actor that leaves entryHash valid (model/services/governance/AuditService.yaml). |
| AC3 | Given the aggregates AuditService/ClassificationLabel and AuditService/Finding, when an instance label weaker than the default of its type is set, then it is refused; and when a finding is raised and then resolved or accepted as a risk, then it moves from open to resolved or to accepted-risk with resolvedAt, a finding without an evidence entry is refused, and nothing leaves resolved or accepted-risk (model/services/governance/AuditService.yaml). |
| AC4 | Given an empty audit-sql, when the migrations run, then AuditEntries, ChainHeads, Classifications, RedactionRules and Findings exist with the columns and indexes of docs/planes/trust-operations/governance/services/audit-service/ddl.md, the primary key of RedactionRules is TenantId and RuleId, which is the correction of the key of the model reported under ADR-0015 amendment D113, so that two tenants hold a rule of the same identifier as two rows, a second entry with the same tenant and sequence and a second label for the same tenant, resource type and resource are refused by their unique indexes, rows of two tenants read under the scope of one tenant return only the rows of that tenant, and a blob written to audit-immutable can be neither overwritten nor removed (ADR-0019). |
| Traces: services | AuditService |
| Traces: aggregates | AuditService/AuditEntry, AuditService/ClassificationLabel, AuditService/Finding |
| Traces: descriptors | audit-evidence-v1 |
| Traces: adrs | ADR-0015, ADR-0019, ADR-0028 |
| Traces: requirements | NFR-04 |
| Depends on | feature:component-base-template-factory-profile, feature:component-base-template-findings, feature:contracts-package, feature:repository-and-pipeline-conventions |
| Sources | model/services/governance/AuditService.yaml, model/stores.yaml, docs/planes/trust-operations/governance/services/audit-service/ddl.md, docs/planes/trust-operations/governance/services/audit-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-232 Domain model: the AuditEntry, ClassificationLabel and Finding aggregates with RedactionRule, EvidenceKind, DataClass and FindingSeverity |
implementation | The aggregates AuditEntry, ClassificationLabel with its entity RedactionRule, and Finding with the fields and the enums EvidenceKind, DataClass and FindingSeverity of model/services/governance/AuditService.yaml; an entry is append-only and admits only the redaction of a personal identifier of its actor; an instance label weaker than the default of its type is refused; a finding is raised open with at least one evidence entry and ends resolved or accepted-risk, the value acknowledged being kept in the type and reached by no operation; unit tests cover every state change, every refusal and every invariant the aggregates can enforce. | ConnectSoft.AI.SoftwareFactory.AuditService |
AIFACTORY-TASK-233 Persistence in audit-sql and audit-immutable: migrations and mappings of AuditEntries, ChainHeads, Classifications, RedactionRules and Findings and the write-once container |
migration | Migrations and mappings of the five tables of the model with their columns, the unique indexes UX_Audit_Tenant_Sequence and UX_Classifications_Resource and the indexes IX_Audit_Run, IX_Audit_Tenant_RecordedAt and IX_Findings_Tenant_State; the primary key of RedactionRules is TenantId and RuleId, the correction of the key of model/services/governance/AuditService.yaml reported under ADR-0015 amendment D113, so the data definition page is cited for columns and indexes only until it is regenerated; every mapping carries the tenant row filter of the Factory profile; the mapping of AuditEntries has no update and no delete beyond the redaction of AIFACTORY-US-969; no column holds prompt text, a payload or a secret value; the container of audit-immutable is provisioned with its write-once policy behind one mirror port; mapping tests run against an isolated test database, never a shared one. | ConnectSoft.AI.SoftwareFactory.AuditService |
AIFACTORY-TASK-3857 Verify the scaffold, the aggregates and the stores of AuditService |
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-961: the unchanged scaffold with the Factory profile, the append-only entry, the refused weaker instance label, the state changes of a finding, the five tables with their unique indexes and the tenant row filter against an isolated database, the two tenants that hold a redaction rule of the same identifier as two rows, and the write-once behaviour of the mirror container. |
ConnectSoft.AI.SoftwareFactory.AuditService |
AIFACTORY-US-962: AuditService host: six REST routes and four gRPC methods behind scope policies, messaging with the five events of the model, the evidence topic and the consumed events, and four 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 ten operations as the model does. The REST operations are SearchAudit, ListClassifications and ListFindings under the scope factory.audit.read, ExportAudit under factory.audit.export, of class external and idempotent on the Idempotency-Key header, and SetClassification, of class production, and ResolveFinding, of class shared-write, under factory.audit.admin, both with natural idempotency. The internal gRPC methods of the service Audit are Record, Redact and RaiseFindings, of class shared-write, and Classify, a read, none of them streaming; RaiseFindings takes findings-v1, replies ack-v1 and requires the service scope factory.audit.write (D133). 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 is answered 403, and the audience a user token must carry is the one of the Governance gateway that fronts the service from I1 (D127), 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 AuditService, and RaiseFindings the scope factory.audit.write: 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 the model does not list for an operation are given by the host and reported to the owner as codes the model omits: 401 for a missing token, 400 for a request that fails validation or an ExportAudit call without its key header, 409 on ExportAudit for a key reused with another input and on ResolveFinding for a second, different resolution, and 503 while a required dependency does not answer. The OpenAPI document and the proto fix the messages, and three differences between the descriptors the model names and what the methods carry are stated by a contract test and reported. Audit.Record takes the submitted shape of audit-evidence-v1, the record without chainHash, which the contracts package holds beside the stored shape, and replies ack-v1. Audit.Classify is modelled with execution-scope-v1 as its request and policy-decision-v1 as its reply; neither schema has a member for a resource, a data class, a retention, a redaction rule or a residency, so the proto carries the scope in the shape of the first and adds the resource to the request and the class, the retention, the rule identifiers and the residency to the reply as fields. Audit.Redact is modelled with artifact-v1 on both sides, and the proto adds the resource whose label applies and the projection to the request and the applied rule identifiers to the reply. The schema of audit-evidence-v1 and the aggregate AuditEntry also differ, and the contract test lists every member they do not share: evidenceId against entryId, occurredAt against recordedAt, subject against target, chainHash against entryHash; policyDecisionId, redactions and the approval identifier of the correlation, which only the schema has; and sequence, kind, sourceEvent, correlationId, causationId and previousHash, which only the aggregate has. Messaging follows the Orleans profile of the base template: the outbox writer enlists in the unit of work of a command, a handler and a worker step, and the dispatcher of the audit messaging profile publishes the five events of the model in the run event envelope of the pinned contracts package. The service subscribes to audit.evidence.v1.evidence-submitted, the topic of the command SubmitEvidence, with the event type and the topic constant of the contracts package, and publishes nothing on it: its own acts are appended directly. The inbox registers 126 of the 127 consumed events of the model, from 45 producers, with deduplication on the event id: the 125 that RecordEvidence handles, RunAccepted of RunControlService among them (D126, D135), and ToolEffectUncertain for RaiseUncertainFinding. A producer that arrives in a later increment is registered now, because the model lists its event for this service, and its handler is proven with a fixture event built from the contracts package. The one event that is not registered is DeletionOrderIssued of RetentionResidencyService: its handler RedactOnDeletionOrder is built in I4 with that service. A test compares the registrations with the consumed events of the model in both directions. A handler that keeps failing is retried with back-off, and its delivery is poisoned at MaxAttempts of the subscriber, a contract failure at once; a poisoned delivery is visible in the poison metric of the adapter and is recovered through IOutboxRecovery, as AIFACTORY-US-226 of feature component-base-template-factory-profile delivers. This poisoned state is what the PBIs of this feature mean when an event is kept and never dropped; the feature builds no failed work store of its own. The section also declares the internal work messages of the service, each with a subscription of the service itself: the mirror write and the export work. No message of the service depends on deferred delivery. The four workers are hosted with their modelled triggers: EvidenceWriter on the consumed events with an exponential retry of ten attempts from ten seconds, the idempotency key of source event and event id and one execution at a time per tenant; ChainVerifier daily at one with a fixed retry of three attempts six hundred seconds apart, the key of tenant and day and at most two parallel executions; RetentionAndRedactionSweeper daily at three with the same retry, the key entryId and at most two parallel executions; and ExportWorker on an export request with an exponential retry of five attempts from three hundred seconds, the key of project and export request and one execution at a time per tenant. The schedule of each of the two scheduled workers is read from configuration, Governance:Audit:ChainVerifierSchedule and Governance:Audit:RetentionSweeperSchedule, with the schedule of the model as its default, so that an acceptance deployment lets a run fall inside its suite without a trigger (AIFACTORY-US-019); the options of the model list neither key, which is reported to the owner. The host offers no route that triggers a worker on demand. A fifth schedule, the sweep of unresolved uncertain effects, has no worker row in the model; AIFACTORY-US-970 hosts it and reports the missing row. What each operation, handler and worker does is delivered by AIFACTORY-US-964 to AIFACTORY-US-970.
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 AuditService/SearchAudit, AuditService/ExportAudit, AuditService/ListClassifications, AuditService/SetClassification, AuditService/ListFindings and AuditService/ResolveFinding and the methods AuditService/Audit.Record, AuditService/Audit.Classify, AuditService/Audit.Redact and AuditService/Audit.RaiseFindings are hosted with the scope, the side-effect class and the idempotency rule of model/services/governance/AuditService.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 appends an AuditService/AuditEntry and is rolled back and one that commits, when the outbox of the audit messaging profile is read, then the first left no record and the second left its record in the transaction of the change, and 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, the subscription to audit.evidence.v1.evidence-submitted and the internal work messages of the service, declares no publication of the evidence event, and a publish of a message the section does not declare is refused (ADR-0014, ADR-0012). |
| AC4 | Given the consumed events of model/services/governance/AuditService.yaml and a fixture publisher for each, built from the pinned contracts package, when the registrations of the inbox are compared with the model and each event is delivered twice under one event id, then 126 events are registered, each reaches its handler once, a consumed event of the model without a registration and a registration without a consumed event fail the test, DeletionOrderIssued reaches no handler, a handler that keeps failing is poisoned at MaxAttempts and recovered through IOutboxRecovery without a second effect, a schedule of ChainVerifier or RetentionAndRedactionSweeper that fires twice under one idempotency key runs once, and a schedule set through Governance:Audit:ChainVerifierSchedule replaces the default of the model. |
| AC5 | Given the golden files of the proto and of the OpenAPI document, when the contract test compares the message of AuditService/Audit.Record with the submitted shape of docs/reference/schemas/audit-evidence.schema.json, then the shared members are equal in name and type, a request that carries chainHash is refused, the test lists every member the schema and the aggregate AuditService/AuditEntry do not share and every field the proto adds to the descriptors of AuditService/Audit.Classify and AuditService/Audit.Redact, and a change of either side fails it. |
| Traces: services | AuditService |
| Traces: aggregates | AuditService/AuditEntry |
| Traces: apis | AuditService/SearchAudit, AuditService/ExportAudit, AuditService/ListClassifications, AuditService/SetClassification, AuditService/ListFindings, AuditService/ResolveFinding, AuditService/Audit.Record, AuditService/Audit.Classify, AuditService/Audit.Redact, AuditService/Audit.RaiseFindings |
| Traces: events | AuditService/AuditEntryRecorded, AuditService/AuditChainVerified, AuditService/ClassificationChanged, AuditService/FindingRaised, AuditService/FindingResolved |
| Traces: descriptors | audit-evidence-v1, findings-v1, ack-v1, execution-scope-v1, policy-decision-v1, artifact-v1, run-event-envelope-v1 |
| Traces: adrs | ADR-0012, ADR-0014, ADR-0015, ADR-0028 |
| Depends on | AIFACTORY-US-961, feature:component-base-template-factory-profile, feature:contracts-package |
| Sources | model/services/governance/AuditService.yaml, docs/reference/schemas/audit-evidence.schema.json, docs/reference/schemas/execution-scope.schema.json, docs/reference/schemas/policy-decision.schema.json, docs/reference/schemas/artifact.schema.json, docs/planes/trust-operations/governance/services/audit-service/index.md#apis, docs/planes/trust-operations/governance/services/audit-service/index.md#messages, docs/planes/trust-operations/governance/services/audit-service/index.md#workers-and-jobs |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-234 Contract and hosting of the surface: service descriptor, OpenAPI document and proto of the 6 REST and 4 gRPC operations behind their scope policies |
contract | The service descriptor file lists SearchAudit, ExportAudit, ListClassifications, SetClassification, ListFindings, ResolveFinding and Audit.Record, Audit.Classify, Audit.Redact and Audit.RaiseFindings with scope, side-effect class, idempotency and response codes as model/services/governance/AuditService.yaml does; the six routes are hosted behind the policies of factory.audit.read, factory.audit.export and factory.audit.admin with problem responses, the Idempotency-Key filter of ExportAudit and the audience of the Governance gateway for user tokens; the four methods are hosted behind the workload policy of the service scope, Audit.RaiseFindings behind factory.audit.write with findings-v1 as request and ack-v1 as reply; the OpenAPI document and the proto fix the messages by golden files: Audit.Record takes the submitted shape of audit-evidence-v1 without chainHash and replies ack-v1, Audit.Classify carries the scope in the shape of execution-scope-v1 with the resource as a field and replies the class, the retention, the rule identifiers and the residency as fields, and Audit.Redact carries artifact-v1 with the resource and the projection in the request and the applied rule identifiers in the reply; the contract test lists every member docs/reference/schemas/audit-evidence.schema.json and the aggregate AuditEntry do not share and every field added to a descriptor; the behaviour of each operation is delivered by AIFACTORY-US-964 to AIFACTORY-US-970, not here. | ConnectSoft.AI.SoftwareFactory.AuditService |
AIFACTORY-TASK-235 Messaging skeleton: outbox and inbox wiring of the audit profile for the 5 events of the model, the evidence topic, the internal work messages and 126 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 audit messaging profile publishes AuditEntryRecorded, AuditChainVerified, ClassificationChanged, FindingRaised and FindingResolved 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 the subscription to audit.evidence.v1.evidence-submitted with the event type and the topic constant of the pinned contracts package and no publication on it, and the internal work messages of the mirror write and the export work, each with a subscription of the service itself, none of them deferred; the inbox registers 126 of the 127 consumed events of the model with deduplication on the event id, the 125 of RecordEvidence with RunAccepted among them and ToolEffectUncertain, the events of producers of later increments among them; DeletionOrderIssued of RetentionResidencyService is not subscribed, its handler RedactOnDeletionOrder being built in I4 with that service; a test compares the registrations with the consumed events of the model in both directions; what each handler does is delivered by AIFACTORY-US-964 and AIFACTORY-US-970. | ConnectSoft.AI.SoftwareFactory.AuditService |
AIFACTORY-TASK-236 Worker hosting skeleton: triggers, retry policies and partitioning of EvidenceWriter, ChainVerifier, RetentionAndRedactionSweeper and ExportWorker |
implementation | EvidenceWriter is hosted on the consumed events with an exponential retry of ten attempts from ten seconds, the idempotency key of source event and event id and one execution at a time per tenant partition; ChainVerifier on the schedule 0 1 * * * with a fixed retry of three attempts six hundred seconds apart, the key of tenant and day and at most two parallel executions partitioned by tenant; RetentionAndRedactionSweeper on the schedule 0 3 * * * with the same retry, the key entryId and at most two parallel executions; ExportWorker as the consumer of the export work message with an exponential retry of five attempts from three hundred seconds, the key of project and export request and one execution at a time per tenant; the schedules of ChainVerifier and RetentionAndRedactionSweeper are read from Governance:Audit:ChainVerifierSchedule and Governance:Audit:RetentionSweeperSchedule with the schedule of the model as default, two keys the options of the model do not list, and no route triggers a worker on demand; a duplicate trigger and a redelivered work message have no second effect; what each worker does is delivered by AIFACTORY-US-964, AIFACTORY-US-965, AIFACTORY-US-967 and AIFACTORY-US-969. | ConnectSoft.AI.SoftwareFactory.AuditService |
AIFACTORY-TASK-3858 Verify the hosted surface, the messaging profile and the hosted workers of AuditService |
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-962: 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 declared entries of the OrleansMessaging section with the evidence subscription and without a publication of the evidence event, the refused undeclared publish, the 126 registrations compared with model/services/governance/AuditService.yaml in both directions and deduplicated under fixture publishers, the unregistered DeletionOrderIssued, the poisoned and recovered delivery of a failing handler, the duplicate worker trigger, the schedule read from configuration, and the golden files compared with docs/reference/schemas/audit-evidence.schema.json with the complete list of members that are not shared. |
ConnectSoft.AI.SoftwareFactory.AuditService |
AIFACTORY-US-963: AuditService keeps one chain per tenant, filters every query by tenant and project, signs with a key that stays in the vault and keeps evidence text and content out of telemetry¶
enabling
AuditService holds the evidence of every tenant, and the model classifies its data as restricted, so isolation, the custody of the signing key and the silence of its telemetry are deliverables of their own. Tenant isolation is the row filter of the profile: every query on AuditEntries, ChainHeads, Classifications, RedactionRules and Findings carries the tenant of the trusted scope, so an entry, a label, a rule or a finding of another tenant is invisible. A request that addresses a finding by identifier is answered 404 for a finding of another tenant, the same answer as for an identifier that does not exist, and a search or a list returns nothing of another tenant and never confirms that it exists (ADR-0015). The chain is per tenant as well: an entry is appended to the chain of the tenant its evidence names and to no other. The tenant of an evidence event is the trusted tenant of its envelope; a record whose tenantId differs from it is not appended: its delivery is a contract failure that the inbox poisons at once, where it stays visible in the poison metric and recoverable through IOutboxRecovery (AIFACTORY-US-226 of feature component-base-template-factory-profile), and Audit.Record refuses a record whose tenant is not the one the workload forwards with INVALID_ARGUMENT, because the tenant never comes from a body. Inside a tenant the project is the second boundary for evidence. An entry carries the optional project of the act; a user token reads the entries of a project only with one of the roles of the model in that project, Reviewer, Operator, Workspace admin or Observer, or with the tenant-wide Platform admin role. An entry without a project belongs to its tenant and is read only with a tenant-wide role, Platform admin or an Observer assigned at the tenant, as the role table of ADR-0015 allows. A caller that names a project of its own tenant in which it holds no role is answered 403, because a missing right inside the own tenant is never answered as not found. Classification labels and findings belong to the tenant and carry no project; factory.audit.admin and factory.audit.export are scopes the model gives to the Platform admin and to tenant auditors. The two secrets of the model reach the service as secret references and never as values: audit-chain-key, the key in Azure Key Vault that signs the head of a chain and that Governance:Audit:ChainSigningKeyId names, and messaging-transport; their rotation periods are the ones the model states and are applied by the platform. The signing key never leaves the vault: the service asks the vault to sign through one signing port, holds no key material, and an architecture test fails when another type references the vault client. The service is unready while a reference cannot be resolved, and readiness names each required dependency that does not answer: audit-sql, audit-immutable, Key Vault and ArtifactService, which the model marks required. Telemetry follows the Factory conventions through the single enrichment registration of the pinned observability libraries. The four instruments of the model are created through the instrument helper: connectsoft.factory.audit.entries with tenant and kind, connectsoft.factory.audit.chain_lag with tenant, the age of the oldest consumed event not yet appended, connectsoft.factory.audit.chain_valid with tenant, and connectsoft.factory.audit.findings_open with tenant and severity. The two objectives of the model are read on them: the evidence lag from event to chain, thirty seconds at the 95th percentile, for which the model gives no histogram and which is watched on chain_lag, and a valid chain verification every day, watched on chain_valid. Metrics carry tenant and, where an entry names one, project; activities and log records carry tenant and project, and run, step and attempt when the evidence names a run. No reason text, no actor identifier, no target and no content that Audit.Redact handles reaches a metric, an activity or a log record: the entry identifier, the sequence and the kind stand in their place (ADR-0019).
Acceptance criteria
| AC1 | Given entries, labels and findings of two tenants, when a caller of the first tenant searches through AuditService/SearchAudit for a run of the second, lists findings and labels, and addresses a finding of the second through AuditService/ResolveFinding, then the search and the lists return nothing of the second tenant, the finding is answered 404 exactly as an unknown identifier, an evidence event whose record names another tenant than its envelope is not appended and its delivery is poisoned in the inbox as a contract failure, and AuditService/Audit.Record with a record of another tenant than the forwarded one is refused with INVALID_ARGUMENT (ADR-0015). |
| AC2 | Given entries of two projects of one tenant and entries without a project, when AuditService/SearchAudit is called with a token that holds a role in the first project only, with the Platform admin role and with an Observer role assigned at the tenant, then the first receives the entries of its project and is answered 403 when it names the second project, and the two tenant-wide roles receive the entries of both projects and the entries without a project (docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md). |
| AC3 | Given a start without a resolvable secret reference for audit-chain-key or for messaging-transport, when readiness is probed, then the service is unready and names the missing reference; and when the architecture test runs, then the signing port is the only type that references the vault client, no type of the solution holds key material, and neither the configuration of the repository nor any log record holds a secret value (model/services/governance/AuditService.yaml). |
| AC4 | Given evidence whose reason, actor and target carry a marker text and content with a marker that is redacted through AuditService/Audit.Redact, when the collected metrics, activities and log records of an append, a search, an export, a verification and a redaction are scanned, then none holds a marker, the metrics carry their modelled dimensions with tenant, and the activities and log records of an entry that names a run carry run, step and attempt (ADR-0019). |
| Traces: services | AuditService |
| Traces: aggregates | AuditService/AuditEntry, AuditService/Finding |
| Traces: apis | AuditService/SearchAudit, AuditService/ResolveFinding, AuditService/Audit.Record, AuditService/Audit.Redact |
| Traces: adrs | ADR-0015, ADR-0019 |
| Traces: requirements | NFR-03, NFR-10 |
| Relates: nfrs | NFR-10 |
| Depends on | AIFACTORY-US-961, AIFACTORY-US-962, feature:component-base-template-factory-profile, feature:component-observability-factory-conventions |
| Sources | model/services/governance/AuditService.yaml, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/architecture/data-governance.md#logging-and-telemetry, docs/planes/trust-operations/governance/security.md#evidence-integrity, docs/planes/trust-operations/governance/services/audit-service/index.md#security, docs/planes/trust-operations/governance/services/audit-service/index.md#metrics-and-observability |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-237 Security, tenancy and telemetry of AuditService |
implementation | Every query of the five tables runs under the tenant row filter of the Factory profile, so a finding of another tenant is answered 404 exactly as an unknown one and no search or list returns a row of another tenant; an entry is appended to the chain of the tenant of its envelope or of the forwarded scope only, a record of another tenant being poisoned in the inbox as a contract failure or refused with INVALID_ARGUMENT; the entries of a project are read with one of the roles Reviewer, Operator, Workspace admin or Observer in that project, with an Observer role assigned at the tenant or with the Platform admin role, the entries without a project with a tenant-wide role only, and another project of the own tenant is answered 403; audit-chain-key and messaging-transport are read as secret references, a missing reference keeps the service unready, and one signing port asks Azure Key Vault to sign, so that no key material is in the service; readiness names audit-sql, audit-immutable, Key Vault and ArtifactService; the instruments connectsoft.factory.audit.entries, connectsoft.factory.audit.chain_lag, connectsoft.factory.audit.chain_valid and connectsoft.factory.audit.findings_open are created through the instrument helper with their modelled dimensions; no reason text, actor identifier, target or content reaches a metric, an activity or a log record. | ConnectSoft.AI.SoftwareFactory.AuditService |
AIFACTORY-TASK-3859 Two-tenant fixture with user and workload tokens, publishers of every consumed event, fakes of the artifact store, the mirror and the signing key, and a telemetry collector |
fixture | The acceptance suite holds two tenants with two projects each, user tokens of the Governance gateway audience with and without factory.audit.read, factory.audit.export and factory.audit.admin, with a role in one project, with the Platform admin role and with an Observer role assigned at the tenant, workload tokens with and without the service scope naming AuditService, a publisher for every consumed event of model/services/governance/AuditService.yaml and for AuditEvidenceSubmitted built from the pinned contracts package, evidence and content that carry a marker text, a fake of ArtifactService that records Artifacts.Store and Artifacts.Fetch, keeps stored content by hash and can stop answering, a fake mirror behind the mirror port that is write-once and can stop answering, a fake of the signing port that signs and verifies with a test key, names the key version and can stop answering, a clock the suite moves, and an in-memory collector of metrics, activities, log records and outbox records; the fixture serves the suites of AIFACTORY-US-963 to AIFACTORY-US-970. | ConnectSoft.AI.SoftwareFactory.AuditService |
AIFACTORY-TASK-3860 Verify tenancy, the project boundary, secret references and telemetry of AuditService |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Feature=TenancyAndTelemetry" and the architecture tests; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-963: the empty search and lists for another tenant, 404 for a foreign finding equal to the answer for an unknown one, the record of another tenant that is not appended, the entries of a project read with a role in it and 403 for another project of the tenant, the entries without a project read with a tenant-wide role only, the unready start without a secret reference, the single signing port, and the scan of metrics, activities and log records for the marker text. |
ConnectSoft.AI.SoftwareFactory.AuditService |
AIFACTORY-US-964: Append submitted evidence, recorded events and directly recorded commands once each to the hash chain of their tenant and mirror every entry to the immutable store¶
behavior
Every piece of evidence ends in one append, whichever of three paths it arrives on. The first path is the evidence event. A Factory service writes an audit-evidence-v1 record to its own outbox in the transaction of its command, and the record arrives as AuditEvidenceSubmitted on audit.evidence.v1.evidence-submitted in the run event envelope; the command SubmitEvidence appends it once per evidence identifier, which is also the event id (D115). The second path is the consumed events. RecordEvidence, run by the worker EvidenceWriter, turns each of the 125 integration events the model lists for it into one entry. A mapping table, one reviewed file of the repository with one row per consumed event of the model and fixed by a golden file, gives the entry its kind, its action, the payload member that names the target with its version or hash, the member that names the acting identity where the payload has one, and the outcome. The rows follow one default rule, applied in this order, so that no developer classifies the trail anew. The family is ApprovalDecision for the approval events, PolicyDecision for PolicyDecisionRecorded, Publication for publications and activations, CredentialIssuance for the events of SecretBrokerService, ToolEffect for the tool events, DataLifecycle for deletions, retention and offboarding, AccessChange for membership, delegation and grant changes, Export for exports, and Command for every other event. The action is the event name. The target is the payload member that identifies the aggregate of the event, with the version or hash member where the payload has one. The outcome is the value of the payload member that names a state, a decision or a result where the event has one, and the fixed value recorded where it has none. Tenant, project, run, correlation and causation come from the envelope, sourceEvent is the producing service and the event name, and no other member of the payload is copied, because evidence never holds prompt text, payloads or secret values. The third path is AuditService/Audit.Record, by which a service with a workload token that holds the service scope appends evidence of a command that is not an event; in this increment no service of the model calls it, so it is proven with a workload of the fixture. All three use one append routine. It takes the chain of the tenant exclusively, so that one entry is appended per tenant at a time whichever path it came by, gives the entry the next sequence of the tenant and the entryHash of its predecessor as previousHash, the first entry of a tenant taking a fixed starting value, and computes entryHash over the canonical form of the record together with previousHash, in the text form the Factory uses for a hash, fixed by a golden file. Before hashing, the text members pass the audit profile of the pinned Compliance library once more, so that a record that arrives unredacted is stored redacted. A personal identifier of the actor enters the hash as a salted digest that is kept beside it, so that the later redaction of the identifier leaves the hash valid (AIFACTORY-US-969). In one transaction the routine writes the AuditEntries row, the AuditEntryRecorded outbox record and the mirror work message; the unique index on tenant and sequence refuses what the exclusive append missed, and the append is repeated. A mirror writer then writes each entry in the order of its sequence to audit-immutable as the canonical record with its hash, with the digest in place of a personal identifier, so that the write-once store never holds one. The members of audit-evidence-v1 for which the model gives AuditEntries no column, occurredAt, policyDecisionId, redactions and the approval identifier, are part of the canonical record and of the mirror and are not columns; this is reported. Duplicates add nothing: an evidence identifier that is already an entry and an event whose source event and event id were already recorded are acknowledged and skipped, and Audit.Record answers a repeated record with the same content with OK and ack-v1 and the same identifier with other content with ALREADY_EXISTS. A record that fails the schema, that carries chainHash, or whose tenant is not the tenant of its envelope or of the forwarded scope is not appended: over gRPC it is refused with INVALID_ARGUMENT, and as an event its delivery is a contract failure that the inbox poisons at once and counts, the poisoned state AIFACTORY-US-962 describes. The failure modes of the model are kept. When audit-immutable does not answer, appends to audit-sql continue, the mirror work waits in the outbox and is written in order when the store returns, and the chain is not broken. When audit-sql does not answer, a handler fails and the inbox redelivers it by the retry policy of EvidenceWriter; an event whose attempts are used up is poisoned in the inbox, visible in the poison metric of the adapter and recoverable through IOutboxRecovery (AIFACTORY-US-226 of feature component-base-template-factory-profile), and is never dropped, and connectsoft.factory.audit.chain_lag shows the age of the oldest event not yet appended while the partitions of other tenants keep writing. Two acts are fixed by decision. A run submission is audited through RunAccepted of RunControlService, which RecordEvidence appends as the evidence of the submission, with the family Command by the default rule and the requester, the pinned release and the policy revision of the accepted run in its target and outcome (D126, D135). A credential issuance leaves exactly one entry, the one RecordEvidence appends for CredentialIssued, which names the policy decision that allowed it, because SecretBrokerService submits no evidence record of its own for an issuance (D126, D135). AuditEntryRecorded carries entryId, tenantId, sequence, kind, action and the optional runId and is published on audit.evidence.v1.audit-entry-recorded; since the dashboards of I4 keep the run projections and the overviews only (D131), the model lists no consumer of it. Three points are reported to the owner and decided nowhere here: the stored record is audit-evidence-v1 with a closed list of fourteen actions while the consumed events name many more acts and several fit none of the nine families of EvidenceKind, so the default rule sends them to Command and the mapping file needs the confirmation of the owner; the two representatives of generated products among the producers have no Factory repository; and the model gives the lag objective no instrument of its own.
Acceptance criteria
| AC1 | Given an audit-evidence-v1 submission delivered as AuditEvidenceSubmitted on audit.evidence.v1.evidence-submitted, when SubmitEvidence handles it, then one AuditService/AuditEntry exists whose identifier is the evidence identifier, with the next sequence of the tenant of the envelope, the hash of its predecessor as previousHash and an entryHash that follows from the canonical record, and the AuditService/AuditEntryRecorded outbox record was written in the same transaction; the same event delivered twice leaves one entry, and a record that fails docs/reference/schemas/audit-evidence.schema.json or names another tenant than its envelope is not appended and its delivery is poisoned in the inbox as a contract failure. |
| AC2 | Given the mapping file with its golden file and a fixture event for each of its 125 rows, RunControlService/RunAccepted, RunControlService/ApprovalDecided, PolicyEngineService/PolicyDecisionRecorded, ToolAdapterService/ToolInvoked and SecretBrokerService/CredentialIssued among them, when RecordEvidence handles it, then one AuditService/AuditEntry exists and the test compares its kind, action, target and outcome with the row of that file, the five named events taking the families Command, ApprovalDecision, PolicyDecision, ToolEffect and CredentialIssuance, the issuance once only and with the policy decision it names, and each action being the event name, with tenant, project, run and correlation of the envelope and sourceEvent naming the producer and the event, no other payload member is stored, the same event id delivered twice leaves one entry, and a consumed event of model/services/governance/AuditService.yaml without a row, a row without a consumed event and a row that departs from the golden file each fail the test. |
| AC3 | Given a workload with the service scope, when AuditService/Audit.Record is called with a valid submission, then the reply is ack-v1 after the entry is committed in the chain of the forwarded tenant; a repeated call with the same record is answered OK with ack-v1 and leaves one entry, the same evidence identifier with other content is answered ALREADY_EXISTS and changes nothing, and a call without a workload identity, without the service scope, with an invalid record, with chainHash or with the tenant of another scope is refused with UNAUTHENTICATED, PERMISSION_DENIED or INVALID_ARGUMENT and appends nothing (SCN-AuditService-007, ADR-0015). |
| AC4 | Given evidence of two tenants arrives on all three paths at once, when the entries are read, then each tenant has consecutive sequences without a gap or a duplicate and every previousHash equals the entryHash before it; given the mirror stops answering, then appends continue, the mirror work waits and is written in sequence order when it returns, and the mirror holds every entry once with its hash and without a personal identifier; given audit-sql stops answering, then the event is redelivered by the retry policy of EvidenceWriter, nothing is dropped and connectsoft.factory.audit.chain_lag rises for that tenant only (docs/planes/trust-operations/governance/services/audit-service/index.md). |
| AC5 | Given an entry was appended, when the outbox dispatcher publishes AuditService/AuditEntryRecorded on audit.evidence.v1.audit-entry-recorded, then the event is sent in the run event envelope with entryId, tenantId, sequence, kind, action and, for an entry that names a run, runId, it holds no reason, actor or target, and a transport outage is retried with backoff so the event is neither lost nor duplicated under its event id (SCN-AuditService-010, ADR-0012). |
| Traces: services | AuditService |
| Traces: aggregates | AuditService/AuditEntry |
| Traces: apis | AuditService/Audit.Record |
| Traces: events | AuditService/AuditEntryRecorded, RunControlService/RunAccepted, RunControlService/ApprovalDecided, PolicyEngineService/PolicyDecisionRecorded, ToolAdapterService/ToolInvoked, SecretBrokerService/CredentialIssued |
| Traces: descriptors | audit-evidence-v1, ack-v1, run-event-envelope-v1 |
| Traces: adrs | ADR-0012, ADR-0014, ADR-0015, ADR-0019 |
| Traces: requirements | FR-06, NFR-04 |
| Traces: scenarios | SCN-AuditService-007, SCN-AuditService-010 |
| Relates: nfrs | NFR-04 |
| Depends on | AIFACTORY-US-961, AIFACTORY-US-962, AIFACTORY-US-963, feature:contracts-package, feature:component-compliance-factory-classifications, feature:run-control-service, feature:policy-engine-service, feature:tool-adapter-service, feature:secret-broker-service |
| Sources | model/services/governance/AuditService.yaml, model/scenarios/AuditService.yaml, docs/reference/schemas/audit-evidence.schema.json, docs/planes/trust-operations/governance/events.md, docs/planes/trust-operations/governance/services/audit-service/index.md#failure-and-recovery, docs/planes/trust-operations/governance/security.md#evidence-integrity |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-3861 Append routine of the tenant chain and Audit.Record |
implementation | One append routine takes the chain of a tenant exclusively, assigns the next sequence, sets previousHash to the entryHash of the predecessor or to the fixed starting value, passes the text members through the audit profile of the pinned Compliance library, represents a personal identifier of the actor by a salted digest kept beside it, computes entryHash over the canonical record and previousHash in the hash text form a golden file fixes, and writes the AuditEntries row, the AuditEntryRecorded outbox record and the mirror work message in one transaction, repeating on a refusal of UX_Audit_Tenant_Sequence; Audit.Record validates the submitted shape of audit-evidence-v1, refuses chainHash and a tenant other than the forwarded one with INVALID_ARGUMENT, appends through the routine and replies ack-v1, answers OK with ack-v1 for a repeated record with the same content and ALREADY_EXISTS for the same identifier with other content; connectsoft.factory.audit.entries is recorded by tenant and kind. | ConnectSoft.AI.SoftwareFactory.AuditService |
AIFACTORY-TASK-306 Evidence writer over the submitted evidence and the consumed events |
implementation | The handler of SubmitEvidence appends each audit-evidence-v1 submission that arrives as AuditEvidenceSubmitted once per evidence identifier through the routine of AIFACTORY-TASK-3861; RecordEvidence, run by EvidenceWriter, appends one entry per consumed event from the mapping file of AIFACTORY-TASK-3879, whose row gives kind, action, the target member with its version or hash, the acting identity where the payload has one and the outcome, takes tenant, project, run, correlation and causation from the envelope and sourceEvent from producer and event name, and copies no other payload member; a repeated evidence identifier and a repeated source event and event id add no entry; a record that fails the schema or names another tenant than its envelope is a contract failure that the inbox poisons at once and counts, and an event whose attempts are used up is poisoned and recoverable through IOutboxRecovery, never dropped; connectsoft.factory.audit.chain_lag reports the age of the oldest event not yet appended per tenant. | ConnectSoft.AI.SoftwareFactory.AuditService |
AIFACTORY-TASK-3879 Evidence mapping file of the 124 consumed events with its default rule and its golden file |
contract | One reviewed file of the repository holds one row for each of the 125 events that model/services/governance/AuditService.yaml lists for RecordEvidence, with kind, action, the target member with its version or hash, the member of the acting identity where the payload has one and the outcome; the rows are written by the default rule in this order: ApprovalDecision for the approval events, PolicyDecision for PolicyDecisionRecorded, Publication for publications and activations, CredentialIssuance for the events of SecretBrokerService, ToolEffect for the tool events, DataLifecycle for deletions, retention and offboarding, AccessChange for membership, delegation and grant changes, Export for exports and Command for every other event; the action is the event name, the target is the payload member that identifies the aggregate of the event, and the outcome is the payload member that names a state, a decision or a result, or the fixed value recorded where the event has none; a golden file fixes the file, so that a changed row fails the contract test until the golden file is reviewed again; the test also fails on a consumed event without a row and on a row without a consumed event; the confirmation of the rows by the owner is reported as open. | ConnectSoft.AI.SoftwareFactory.AuditService |
AIFACTORY-TASK-3862 Mirror writer to the immutable store in the order of the tenant sequence |
implementation | The consumer of the mirror work message writes each entry to audit-immutable through the mirror port as the canonical record with its entryHash, with the digest in place of a personal identifier and with the members of audit-evidence-v1 that have no column, once per entry and in the order of the tenant sequence; while the store does not answer the work waits in the outbox and appends to audit-sql continue; when it returns the waiting entries are written in order; a second delivery of the work of an entry writes nothing. | ConnectSoft.AI.SoftwareFactory.AuditService |
AIFACTORY-TASK-3863 Verify the three append paths, the mirror and the event through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-AuditService-007\|Scenario=SCN-AuditService-010)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-964 with the fixture of AIFACTORY-TASK-3859: the entry of a submitted record with its chain members and its outbox record in one transaction, one entry per fixture event of the 125 mapped events, compared with its row of the mapping file of AIFACTORY-TASK-3879, with redeliveries, the accepted call of Audit.Record, the repeated call answered OK, the conflicting call answered ALREADY_EXISTS and its refusals, consecutive sequences of two tenants under concurrent appends on the three paths, the mirror written in order after an outage of the fake mirror, the redelivery after an outage of the store, and the publication and payload of AuditEntryRecorded with a transport outage; the model lists no consumer of the event (D131). |
ConnectSoft.AI.SoftwareFactory.AuditService |
AIFACTORY-US-965: Verify the hash chain of every tenant daily, sign its head with the key in the vault and raise a Critical finding on a break¶
behavior
The chain is proof only when it is checked. The worker ChainVerifier, hosted by AIFACTORY-US-962 daily, takes each tenant that has entries and verifies its chain since the last signed head, the row of the tenant in ChainHeads. It recomputes the entryHash of every entry from its stored record and its previousHash, checks that each previousHash is the entryHash of the entry before it and that the sequences have no gap, and so finds an altered entry, a removed entry and a relinked entry alike. When the span is intact, the worker asks Azure Key Vault through the signing port to sign the hash of the last entry of the span with the key that Governance:Audit:ChainSigningKeyId names; the key never leaves the vault. In one transaction it replaces the head of the tenant, with HeadSequence and HeadHash of that last entry, SignedAt and Signature, writes the AuditChainVerified outbox record with valid true and that head sequence, and appends one entry of the verification through the append routine of AIFACTORY-US-964, because a verification result is itself evidence. The order is exact. The head covers the entries up to the last entry before the verification entry. The verification entry is the first entry after the signed head: it takes the hash of the head as its previousHash, the kind Command and the action chain-verified, names the chain of the tenant with the head sequence and the head hash as its target and the worker as its actor, and has its own AuditEntryRecorded outbox record. The worker holds the chain of the tenant exclusively, as the append routine does, from the check of the last entry to the commit, so that no other entry comes between the signed head and the verification entry. The next run starts with that entry. A span that holds nothing but the verification entry of the previous run is verified and signed, so that the head moves onto that entry, and appends no new verification entry; a tenant whose head already covers its last entry has no span, and a run writes, signs and appends nothing for it. The chain of an idle tenant therefore stops growing after its second run. Two points are corrections of the model and are reported to the owner: the worker row of ChainVerifier lists AuditChainVerified and FindingRaised as its output and not the AuditEntryRecorded of the verification entry, and EvidenceKind has no family for an act of the Audit service itself, so the entry takes Command by the default rule of AIFACTORY-US-964. The stored signature names the version of the key beside the signature bytes, so that a head signed before a rotation of the key still verifies; ChainHeads has no column for the key version, which is reported. connectsoft.factory.audit.chain_valid is set to one for the tenant. When the span is broken, the head is not moved. In one transaction the worker writes AuditChainVerified with valid false and the sequence of the last valid head and raises a finding of severity Critical, the severity the model fixes for a broken chain, in the category of a chain break, with the entries at the break as its evidence; the finding is raised through the routine of AIFACTORY-US-970 with its FindingRaised outbox record, and chain_valid is set to zero. While that finding is open no second one is raised for the same entries. Evidence writing does not stop: as the failure mode of the model says, it continues on a new segment anchored to the last valid head, so the next entry appended for the tenant takes the hash of that head as its previousHash. On a later run the worker recognises the entry that is anchored to the signed head as the start of the new segment, verifies from there and signs the head of the new segment, while the broken span stays named by the finding and is investigated from the immutable mirror, which holds every entry as it was written. The model gives no column that marks a segment, which is reported. When Key Vault does not answer, no head is signed and no AuditChainVerified is written, because the event says the chain was verified and its head signed; the run is repeated by the retry policy of the worker, three attempts six hundred seconds apart, and when they are used up the run ends as failed, which is logged as an error that names the tenant, and the next daily run covers the longer span; the feature builds no failed work store for a scheduled worker. A second trigger for the same tenant and day changes nothing. AuditChainVerified carries tenantId, headSequence and valid and is published on audit.evidence.v1.audit-chain-verified; the model lists no consumer of it, because the dashboards of I4 keep the run projections and the overviews only (D131).
Acceptance criteria
| AC1 | Given a tenant with an intact chain beyond its last signed head, when ChainVerifier runs, then the row of the tenant in ChainHeads holds the sequence and the hash of the last AuditService/AuditEntry of the verified span, a signature made by the signing port that names the key version and verifies, and SignedAt, the AuditService/AuditChainVerified outbox record with valid true and that head sequence was written in the same transaction, and one verification entry with the kind Command and the action chain-verified was appended as the first entry after the head, with the head hash as its previousHash and its own AuditService/AuditEntryRecorded record, also while evidence of the same tenant is appended concurrently; a later run whose span holds only that verification entry moves the signed head onto it and appends none, a run for a tenant without a span writes nothing, and connectsoft.factory.audit.chain_valid is one for the tenant (SCN-AuditService-011). |
| AC2 | Given a chain in which one entry was altered, one was removed or one was relinked after the last signed head, when ChainVerifier runs, then the head is unchanged, AuditService/AuditChainVerified is written with valid false and the sequence of the last valid head, one AuditService/Finding of severity Critical with the entries at the break as its evidence is raised with its AuditService/FindingRaised outbox record in the same transaction, connectsoft.factory.audit.chain_valid is zero, and a run on the next day raises no second finding for the same entries while the first is open (SCN-AuditService-011, docs/planes/trust-operations/governance/security.md). |
| AC3 | Given a broken span and a Critical finding for it, when evidence arrives for the tenant and ChainVerifier runs again, then the next AuditService/AuditEntry took the hash of the last valid head as its previousHash, the worker verifies the new segment from that entry and signs its head, the entries of the broken span are unchanged in audit-sql and in the mirror, and the chains of other tenants were verified and signed in the same runs (model/services/governance/AuditService.yaml). |
| AC4 | Given the signing port does not answer, when ChainVerifier runs, then no head is written and no AuditService/AuditChainVerified is published, the run is repeated at most three times six hundred seconds apart and then ends as failed, logged as an error that names the tenant, a second trigger for the same tenant and day changes nothing, and the next daily run verifies the whole span since the last signed head; no key material is in the service at any time (SCN-AuditService-011). |
| AC5 | Given a verification was committed, when the outbox dispatcher publishes AuditService/AuditChainVerified on audit.evidence.v1.audit-chain-verified, then the event is sent in the run event envelope with tenantId, headSequence and valid, and a transport outage is retried with backoff so the event is neither lost nor duplicated under its event id (SCN-AuditService-011, ADR-0012). |
| Traces: services | AuditService |
| Traces: aggregates | AuditService/AuditEntry, AuditService/Finding |
| Traces: events | AuditService/AuditChainVerified, AuditService/FindingRaised, AuditService/AuditEntryRecorded |
| Traces: descriptors | run-event-envelope-v1 |
| Traces: adrs | ADR-0012, ADR-0019 |
| Traces: requirements | NFR-04, NFR-10 |
| Traces: scenarios | SCN-AuditService-011 |
| Relates: nfrs | NFR-04 |
| Depends on | AIFACTORY-US-961, AIFACTORY-US-962, AIFACTORY-US-963, AIFACTORY-US-964, AIFACTORY-US-970 |
| Sources | model/services/governance/AuditService.yaml, model/scenarios/AuditService.yaml, docs/planes/trust-operations/governance/security.md#evidence-integrity, docs/planes/trust-operations/governance/services/audit-service/index.md#workers-and-jobs, docs/planes/trust-operations/governance/services/audit-service/index.md#failure-and-recovery |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-307 Chain verifier with the daily head signature and the Critical finding on a break |
implementation | On its daily schedule the worker verifies per tenant the entries since the head in ChainHeads by recomputing each entryHash, following each previousHash and checking the sequences for a gap; for an intact span it holds the chain of the tenant exclusively, has the hash of the last entry of the span signed through the signing port with the key of Governance:Audit:ChainSigningKeyId, and in one transaction stores the head of that entry with a signature that names the key version, writes AuditChainVerified with valid true and that head sequence and appends through the routine of AIFACTORY-TASK-3861 one verification entry as the first entry after the head, with the kind Command, the action chain-verified, the head hash as previousHash and its own AuditEntryRecorded record, and sets connectsoft.factory.audit.chain_valid to one; a span that holds only the verification entry of the previous run is verified and signed and appends no verification entry, and a tenant without a span is left untouched; the missing AuditEntryRecorded in the worker row of the model and the missing family of EvidenceKind for an act of the service itself are reported as corrections of the model; for a broken span it leaves the head, writes AuditChainVerified with valid false and raises one Critical finding with the entries at the break through the routine of AIFACTORY-TASK-3876 in one transaction, sets the gauge to zero and raises no second finding for the same entries while the first is open; it recognises the entry anchored to the signed head as the start of a new segment; a signing port that does not answer writes nothing and is retried three times six hundred seconds apart under the idempotency key of tenant and day, after which the run ends as failed and is logged as an error that names the tenant; the chaining of the entries themselves is delivered by AIFACTORY-TASK-3861. | ConnectSoft.AI.SoftwareFactory.AuditService |
AIFACTORY-TASK-3864 Segment anchoring of the append after a broken span |
implementation | The append routine of AIFACTORY-TASK-3861 reads whether the last verification of the tenant found a break and, when it did, gives the next entry the hash of the last valid signed head as previousHash, once per break, so that evidence writing continues on a new segment as the failure mode of the model states; the entries of the broken span are neither changed nor removed; the acceptance suite gains helpers that alter, remove and relink an entry of a fixture chain directly in the isolated test database. | ConnectSoft.AI.SoftwareFactory.AuditService |
AIFACTORY-TASK-3865 Verify the chain verification, the signed head, the break and the event through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-AuditService-011"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-965 with the fixture of AIFACTORY-TASK-3859: the signed head of an intact chain on the last entry of the span with its AuditChainVerified record and its verification entry as the first entry after the head in one transaction, under concurrent appends of the tenant, the later run that moves the head onto that entry and appends none, the run without a span that writes nothing, the unchanged head, the valid false event and the one Critical finding for an altered, a removed and a relinked entry, the new segment anchored to the last valid head and its signed head on a later run, the run without a head while the fake signing port does not answer with its three attempts and the second trigger of the same day, and the publication and payload of AuditChainVerified with a transport outage; the model lists no consumer of the event (D131). |
ConnectSoft.AI.SoftwareFactory.AuditService |
AIFACTORY-US-966: Search the evidence of a tenant by project, kind, actor, run and time and receive every entry with a chain position that can be verified¶
behavior
A caller whose token carries the scope factory.audit.read searches evidence through AuditService/SearchAudit. The filters are the ones the model names: the scope, which is the project, the kind out of the nine families of EvidenceKind, the actor, the run and a time range over recordedAt. The answer is given in pages in the order of the tenant sequence, and each entry carries what the aggregate holds: entryId, sequence, kind, actor, action, target with its version or hash, the redacted reason, outcome, correlationId, causationId, runId, sourceEvent and recordedAt. With it comes the chain position that makes the entry verifiable: its previousHash and entryHash, and the signed head of the tenant that covers it, with head sequence, head hash, signature and signing time, or the statement that no signed head covers the entry yet. A caller that recomputes the hash of a returned entry and follows the links to the head therefore needs to trust nothing but the signature. The search runs under the tenant row filter, so evidence of another tenant is never returned, and a filter that names a run or an actor of another tenant returns an empty page and never an error that would confirm that it exists (ADR-0015). Inside the tenant the project boundary of AIFACTORY-US-963 applies: a token with a role in a project reads the entries of that project, a tenant-wide role reads every project and the entries without a project, and a search that names a project of the tenant in which the caller holds no role is answered 403, as is a caller without the scope. A search without a project filter by a caller with project roles returns the entries of the projects its token grants and nothing else. A filter that cannot be parsed, an unknown kind or a time range whose end is before its start, is refused with 400, a code the model omits for this operation and AIFACTORY-US-962 reports. The search reads through IX_Audit_Run and IX_Audit_Tenant_RecordedAt, writes nothing and appends no evidence of its own, because the model lists a read as no act to record. An entry whose personal identifier was redacted after its retention window is returned in its redacted form, and its position verifies as before (AIFACTORY-US-969). The response is a projection of restricted data: it holds what the entry holds and nothing of the event or the record the entry was made from. A person reaches this route through GovernanceHost, which fronts the service from I1 (D127), and no direct route is built; the suites and the hand-over of AIFACTORY-US-019 call it with tokens of the gateway audience.
Acceptance criteria
| AC1 | Given entries of a run in a project and a caller with factory.audit.read and a role in that project, when AuditService/SearchAudit is called with the run as filter, then the response is 200 with the entries of the run in the order of their sequence, each with kind, actor, action, target, outcome, sourceEvent, recordedAt, previousHash and entryHash, and with the signed head that covers it or the statement that none does yet; nothing is written (SCN-AuditService-001). |
| AC2 | Given entries of several kinds, actors and times, when AuditService/SearchAudit is called with a kind, an actor, a time range and a page cursor, then only the matching AuditService/AuditEntry rows are returned, page after page without a gap or a repetition, and an unknown kind or a time range whose end is before its start is answered 400 (SCN-AuditService-001). |
| AC3 | Given entries of two tenants and of two projects of one tenant, when AuditService/SearchAudit is called without the scope, with a role in the first project only and with a filter that names a run of the other tenant, then the first call is answered 403, the second returns the entries of the first project only and is answered 403 when it names the second project, and the third returns an empty page exactly as for a run that does not exist (SCN-AuditService-001, ADR-0015). |
| AC4 | Given a page returned by AuditService/SearchAudit for a chain with a signed head, when the suite recomputes the hash of each returned entry from its members, follows previousHash to the head and checks the signature of the head, then every position verifies; and an entry whose personal identifier was redacted is returned redacted and verifies as well (SCN-AuditService-001, docs/planes/trust-operations/governance/security.md). |
| Traces: services | AuditService |
| Traces: aggregates | AuditService/AuditEntry |
| Traces: apis | AuditService/SearchAudit |
| Traces: adrs | ADR-0015, ADR-0019 |
| Traces: requirements | NFR-04, NFR-10 |
| Traces: scenarios | SCN-AuditService-001 |
| Relates: nfrs | NFR-10 |
| Depends on | AIFACTORY-US-961, AIFACTORY-US-962, AIFACTORY-US-963, AIFACTORY-US-964, AIFACTORY-US-965 |
| Sources | model/services/governance/AuditService.yaml, model/scenarios/AuditService.yaml, docs/planes/trust-operations/governance/services/audit-service/index.md#apis, docs/planes/trust-operations/governance/security.md#evidence-integrity |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-3866 SearchAudit read model with the filters of the model and the chain position of every entry |
implementation | The read filters the entries of the tenant of the caller by project, kind, actor, run and a time range over recordedAt through IX_Audit_Run and IX_Audit_Tenant_RecordedAt, applies the project boundary of the token, returns pages in the order of the tenant sequence and gives each entry its previousHash, its entryHash and the signed head of ChainHeads that covers it, or the statement that none does yet; a filter that names a run or an actor of another tenant returns an empty page, a project of the tenant without a role of the caller 403, a missing scope 403 and a filter that cannot be parsed 400; the query writes nothing and returns no member of the source event or record beyond the entry. | ConnectSoft.AI.SoftwareFactory.AuditService |
AIFACTORY-TASK-3867 Verify the search, its boundaries and the returned chain positions through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-AuditService-001"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-966 with the fixture of AIFACTORY-TASK-3859: the entries of a run in sequence order with their chain positions, the filters by kind, actor and time with paging, 400 for a filter that cannot be parsed, 403 for a missing scope and for another project of the tenant, the empty page for a run of another tenant, and the recomputed hashes and the head signature of a returned page, a redacted entry included. |
ConnectSoft.AI.SoftwareFactory.AuditService |
AIFACTORY-US-967: Export the evidence of a project in an open format with chain proofs as a package stored by reference in the artifact store¶
behavior
A tenant owns its evidence and receives it in an open format on request (ADR-0019 decision 5). A caller whose token carries the scope factory.audit.export, the Platform admin or an auditor of the tenant, requests the export of one project through AuditService/ExportAudit with an Idempotency-Key. The project is addressed by the path under the tenant row filter. The service keeps no projects: it knows a project by the evidence it holds for it, so a project for which the tenant of the caller holds no entry is answered 404, the same answer for a project that does not exist and for a project of another tenant (ADR-0015). In one transaction the service records the export request with the sequence of the last entry of the tenant at that moment, appends one entry of the request to the chain with the action export-requested, the caller as actor and the project as target, writes its AuditEntryRecorded outbox record and the export work message, and answers 202 with the identifier of the request. The model lists no table for export requests; this delivery adds one by migration, ExportRequests, with the request identifier, tenant, project, key, input hash, state, requesting caller, the sequence up to which the export reaches, the signed head the package is proven against and the reference and hash of the package, and reports the table to the owner. A repeated call under the same key and the same input returns the same request and writes nothing; the same key with another input is refused with 409 and a call without the key header with 400, codes the model omits for this operation; a caller without the scope is refused with 403. The worker ExportWorker, hosted by AIFACTORY-US-962, builds the package once per project and request. It reads the entries of the project up to the recorded sequence and writes them as JSON records, the open format docs/architecture/data-governance.md names for records, in the redacted form in which they are stored and after applying the redaction rules of the labels that classify the exported members; an identifier redacted after its retention window is exported redacted. The package carries chain proofs: for every exported entry its previousHash and entryHash, for the entries of other projects that lie between them in the tenant chain their hashes alone and none of their content, and the signed head the package is proven against, so that a reader verifies the exported entries up to a signed head without seeing evidence of another project. The content of a package is a function of the request alone. At its first attempt the worker records on the request the signed head of the tenant at that moment, with head sequence, head hash, signature and signing time, and every later attempt proves against the recorded head, although ChainVerifier may have moved the head of the tenant in between; an exported entry beyond the recorded head is stated as not yet covered by a signed head. The JSON form is canonical, with a fixed order of members and no time of the build, so that a second attempt for the same request yields the same bytes and the same hash. Two inputs can still change between attempts, a label that classifies an exported member and the redaction of an identifier past its retention window; an attempt after such a change may store a package with another hash, the request names the one its completing transaction recorded, and the case is reported to the owner. The package is stored through ArtifactService/Artifacts.Store as an artifact of kind Export of the project, by reference and hash; AuditService keeps no copy. In one transaction the worker then marks the request completed with the reference and the hash of the package and appends one entry of the completed export, whose target is the artifact with its hash, with its AuditEntryRecorded outbox record. The model has no operation that returns the state or the package of an export, so the requester finds the completed export as that entry through SearchAudit and reads the package from the artifact store under its own scopes; the missing read is reported. The entries of the request and of the completed export are appended directly in the transaction of the act, as every act of the Audit service itself is, and are no evidence events on the evidence topic; the artifact store therefore does not record the completed export as a reference that spares the package from its retention sweep, and the package, a derived copy that can be exported again, follows the retention of the project. Whether the acts of the Audit service itself should travel over the evidence topic as the evidence of every other service does (D115) is reported to the owner. When ArtifactService does not answer, the worker fails the attempt and is repeated by its retry policy, five attempts with exponential backoff from three hundred seconds; the store is idempotent on tenant and hash and the content is fixed by the request, so a repeat leaves one package, also a repeat after a package was stored and the completing transaction failed. When the attempts are used up the last attempt marks the request failed in ExportRequests, whose state names it, the work message is poisoned in the inbox as AIFACTORY-US-962 describes, and a new request under a new key starts again. A redelivered work message of a completed request writes nothing. The content of a package reaches no log record, activity or metric. The service decides no approval for an export and asks none: whether an export needs one is not stated by the model for this service, which has no dependency on the policy service, and is reported.
Acceptance criteria
| AC1 | Given a project with entries and a caller with factory.audit.export, when AuditService/ExportAudit is called with an Idempotency-Key, then the response is 202 with the identifier of the request, the request is recorded with the sequence of the last entry of the tenant, one AuditService/AuditEntry with the action export-requested, the caller as actor and the project as target was appended, and its AuditService/AuditEntryRecorded outbox record and the export work message were written in the same transaction (SCN-AuditService-002). |
| AC2 | Given the same call repeated with the same key and input, then the same request is returned and no second request, entry or work message exists; given the same key with another input, the response is 409; given no key header, 400; given a caller without the scope, 403; given a project for which the tenant of the caller holds no entry, whether it does not exist or belongs to another tenant, 404; and no refusal of AuditService/ExportAudit writes anything (SCN-AuditService-002, ADR-0014, ADR-0015). |
| AC3 | Given a recorded request, when ExportWorker runs, then one package is stored through ArtifactService/Artifacts.Store as an artifact of kind Export of the project, it holds the entries of that project up to the recorded sequence as JSON records in their redacted form and no content of an entry of another project, its chain proofs verify every exported entry up to the signed head recorded on the request, the request is completed with the reference and the hash of the package, and one entry of the completed export with the artifact and its hash as target was appended with its AuditService/AuditEntryRecorded record in the same transaction; a redelivered work message writes nothing (SCN-AuditService-002, docs/architecture/data-governance.md). |
| AC4 | Given ArtifactService/Artifacts.Store does not answer, when ExportWorker runs, then the request stays open, the attempt is repeated by the retry policy up to five times, and a recovery in between completes the export with exactly one package; given a package was stored, the completing transaction failed and ChainVerifier moved the head of the tenant before the next attempt, then that attempt builds the same bytes against the head recorded on the request, the store returns the stored artifact and exactly one package exists; used-up attempts mark the request failed in ExportRequests, and no log record, activity or metric holds content of the package (SCN-AuditService-002, ADR-0019). |
| Traces: services | AuditService, ArtifactService |
| Traces: aggregates | AuditService/AuditEntry |
| Traces: apis | AuditService/ExportAudit, ArtifactService/Artifacts.Store |
| Traces: events | AuditService/AuditEntryRecorded |
| Traces: descriptors | artifact-v1, audit-evidence-v1 |
| Traces: adrs | ADR-0014, ADR-0015, ADR-0019 |
| Traces: requirements | XL-14, NFR-03 |
| Traces: scenarios | SCN-AuditService-002 |
| Relates: nfrs | NFR-03 |
| Depends on | AIFACTORY-US-961, AIFACTORY-US-962, AIFACTORY-US-963, AIFACTORY-US-964, AIFACTORY-US-965, AIFACTORY-US-968, feature:artifact-service |
| Sources | model/services/governance/AuditService.yaml, model/scenarios/AuditService.yaml, model/services/knowledge/ArtifactService.yaml, docs/architecture/data-governance.md#retention-and-deletion, docs/architecture/adr/0019-data-governance.md, docs/planes/trust-operations/governance/services/audit-service/index.md#workers-and-jobs |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-3868 Migration and mapping of the export request table |
migration | A migration adds the table ExportRequests to audit-sql with the request identifier, tenant, project, idempotency key, input hash, state, requesting caller, the sequence up to which the export reaches, the signed head recorded at the first attempt of the worker (head sequence, head hash, signature and signing time), the reference and the hash of the package and the times of request and completion, with a unique index on tenant and idempotency key and the tenant row filter of the profile; the model lists no table for export requests, so the table is reported to the owner as an addition; mapping tests run against an isolated test database. | ConnectSoft.AI.SoftwareFactory.AuditService |
AIFACTORY-TASK-3869 ExportAudit and ExportWorker with the package of JSON records, chain proofs and the store by reference |
implementation | ExportAudit answers 404 for a project without an entry in the tenant of the caller, records the request with the last sequence of the tenant, appends the entry of the request with the action export-requested and writes its AuditEntryRecorded record and the export work message in one transaction, answers 202, returns the first request for the same key and input and 409 for the same key with another input; ExportWorker reads the entries of the project up to the recorded sequence, writes them as JSON records in their redacted form with the redaction rules of the classifying labels applied, records on the request at its first attempt the signed head of the tenant and proves every attempt against that recorded head, adds the chain proofs, that is the hashes of the exported entries, the hashes alone of the entries of other projects between them and the recorded signed head, writes the package in a canonical JSON form without a time of the build so that every attempt for one request yields the same hash, stores the package once through a typed gRPC client of Artifacts.Store as an artifact of kind Export, and completes the request and appends the entry of the completed export in one transaction; an attempt that fails on the artifact store is repeated five times with exponential backoff and then marks the request failed in ExportRequests; an attempt after a stored package and a failed completing transaction stores nothing new; no content of a package is logged. | ConnectSoft.AI.SoftwareFactory.AuditService |
AIFACTORY-TASK-3870 Verify the export request, the package with its proofs and the failure of the artifact store through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-AuditService-002"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-967 with the fixture of AIFACTORY-TASK-3859: the 202 with the request, its entry and its work message in one transaction, the idempotent repeat, the 409, 400, 403 and 404 answers, the one package in the fake of ArtifactService with the entries of one project in redacted form and proofs that verify to a signed head, the completed request with its entry, the redelivered work message, the retries, the recovery and the failed request while Artifacts.Store does not answer, and the attempt after a stored package and a moved head that leaves one package. |
ConnectSoft.AI.SoftwareFactory.AuditService |
AIFACTORY-US-968: Set, list and resolve the classification label of a resource type or instance with its retention, redaction rules and residency, and announce every change¶
behavior
AuditService owns the classification registry that the other services obey: which data class a resource type or one resource has, how long it is retained, which redaction rules apply and where it may reside (ADR-0019 decision 2). A caller whose token carries the scope factory.audit.admin, the Platform admin, sets a label through AuditService/SetClassification. The path names the resource type; the body names the optional resourceId, which is absent for the default of the type, the dataClass out of Public, Internal, Confidential and Restricted, the retentionDays, the redaction rules and the residency. The retention and the residency are inputs of the owner of the data and are never defaulted. Each rule is given with its identifier, its detector out of regex, pii-detector, secret-pattern and custom, its action out of mask, drop and hash, and the projections it applies to out of prompt, context, tool-result, artifact and log; the rules are written to RedactionRules under the key of tenant and rule identifier that AIFACTORY-US-961 builds, and the label holds their identifiers, so a rule identifier that another tenant also uses is accepted as a rule of the caller and changes nothing of that tenant. The model gives a rule no member for a pattern, so the service resolves pii-detector and secret-pattern to the redactors of the pinned Compliance library and a regex or custom rule by its identifier to a redactor registered under that name; a rule whose redactor is not registered is refused, and the missing member is reported to the owner. In one transaction the service writes the label with setBy and setAt, its rules, the ClassificationChanged outbox record and one entry of the change in the chain of the tenant, because a change of a classification is itself evidence; the answer is 200 with the label. The invariant of the aggregate decides the refusal the model lists: a label of one resource may only be stricter than the default of its type, so an instance label weaker than that default is refused with 409, and so is a new default of a type that would leave an existing instance label weaker than it. A type without a label of its own has the class of Governance:Classification:DefaultClass as its default. The operation has natural idempotency: a call that sets what the label already holds answers 200 and writes no event and no entry. A body with an unknown class, detector, action or projection, without retentionDays or without residency is refused with 400, a code the model omits and AIFACTORY-US-962 reports, and a caller without the scope with 403. A caller with factory.audit.read lists the labels of the tenant with their rules through AuditService/ListClassifications, by resource type, and never a label of another tenant. A service resolves the classification of a resource through AuditService/Audit.Classify with a workload token that holds the service scope and the forwarded tenant: the label of the resource when it has one, else the default of its type, else the configured default class with no retention, no rule and no residency of its own, which the reply states as the default. The reply carries the class, the retention, the rule identifiers and the residency; the method is a read, writes nothing and resolves labels of the forwarded tenant only. The model lists ContextBuilderService and ArtifactService as its callers, while neither of them lists the Audit service as a dependency: ContextBuilderService names the policy service for classification decisions and ArtifactService asks the policy service on store and preview and applies ClassificationChanged. The method is therefore built for any workload with the service scope and proven with a workload of the fixture, and the two rows are reported as a correction of the model. ClassificationChanged carries labelId, tenantId, resourceType, the optional resourceId, dataClass and retentionDays and is published on audit.classification.v1.classification-changed; ContextBuilderService, ArtifactService, KnowledgeIngestionService, ModelRouterService and StudioBff apply it from their next operation on, each in its own suite.
Acceptance criteria
| AC1 | Given a caller with factory.audit.admin, when AuditService/SetClassification is called for a resource type with a class, a retention, two rules and a residency, then the response is 200, the AuditService/ClassificationLabel of the type exists in the tenant of the trusted scope with setBy and setAt, the rules are in RedactionRules under the tenant of the caller, a rule identifier that another tenant also uses is accepted and leaves the rule of that tenant unchanged, and the AuditService/ClassificationChanged outbox record and one entry of the change were written in the same transaction (SCN-AuditService-004). |
| AC2 | Given a type whose default is Confidential, when AuditService/SetClassification sets an instance label of class Internal, or sets the default of a type to Restricted while an instance label of class Confidential exists, then the response is 409 and nothing changes; given a call that sets what the label already holds, the response is 200 and no event or entry is written; given an unknown class, detector, action or projection, a rule whose redactor is not registered, no retentionDays or no residency, the response is 400; given a caller without the scope, 403 (SCN-AuditService-004, model/services/governance/AuditService.yaml). |
| AC3 | Given labels of two tenants for several resource types, some for a type and some for one resource, when AuditService/ListClassifications is called by a caller with factory.audit.read, then the response is 200 with the labels of the tenant of the caller and their rules per resource type, no label of the other tenant is returned, a caller without the scope is answered 403, and nothing is written (SCN-AuditService-003, ADR-0015). |
| AC4 | Given a resource with a label of its own, a resource whose type has a default and a resource of a type without any label, when a workload with the service scope calls AuditService/Audit.Classify for each, then the reply carries the class, the retention, the rule identifiers and the residency of the instance label, of the type default, and the class of Governance:Classification:DefaultClass stated as the default with no retention and no rule; a call without a workload identity, without the service scope or without a resource type is refused with UNAUTHENTICATED, PERMISSION_DENIED or INVALID_ARGUMENT, and a label of another tenant is never resolved (SCN-AuditService-008, ADR-0015). |
| AC5 | Given a label was changed, when the outbox dispatcher publishes AuditService/ClassificationChanged on audit.classification.v1.classification-changed, then the event is sent in the run event envelope with labelId, tenantId, resourceType, dataClass, retentionDays and, for the label of one resource, resourceId, and a transport outage is retried with backoff so the event is neither lost nor duplicated under its event id (SCN-AuditService-012, ADR-0012). |
| Traces: services | AuditService |
| Traces: aggregates | AuditService/ClassificationLabel |
| Traces: apis | AuditService/SetClassification, AuditService/ListClassifications, AuditService/Audit.Classify |
| Traces: events | AuditService/ClassificationChanged |
| Traces: descriptors | execution-scope-v1, policy-decision-v1, run-event-envelope-v1 |
| Traces: adrs | ADR-0012, ADR-0015, ADR-0019 |
| Traces: requirements | NFR-03, FR-08 |
| Traces: scenarios | SCN-AuditService-003, SCN-AuditService-004, SCN-AuditService-008, SCN-AuditService-012 |
| Relates: nfrs | NFR-03 |
| Depends on | AIFACTORY-US-961, AIFACTORY-US-962, AIFACTORY-US-963, AIFACTORY-US-964, feature:component-compliance-factory-classifications |
| Sources | model/services/governance/AuditService.yaml, model/scenarios/AuditService.yaml, model/services/knowledge/ContextBuilderService.yaml, model/services/knowledge/ArtifactService.yaml, docs/architecture/data-governance.md#classification, docs/architecture/adr/0019-data-governance.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-308 Classification registry: SetClassification and ListClassifications with redaction rules and the ClassificationChanged outbox record |
implementation | SetClassification writes the label of a resource type or of one resource with dataClass, retentionDays, residency, setBy and setAt, upserts its rules in RedactionRules by tenant and rule identifier, the key AIFACTORY-TASK-233 builds, so that an identifier another tenant uses is a rule of the caller alone, and writes ClassificationChanged and one entry of the change through the append routine of AIFACTORY-TASK-3861 in one transaction; it resolves pii-detector and secret-pattern to the redactors of the pinned Compliance library and a regex or custom rule by its identifier to a registered redactor, and refuses a rule without one; an instance label weaker than the default of its type, and a default that would leave an instance label weaker, answer 409, the default of a type without a label being Governance:Classification:DefaultClass; a call that changes nothing answers 200 without an event; an invalid body, one without retentionDays or without residency among them, answers 400 and a missing scope 403; ListClassifications returns the labels of the tenant with their rules per resource type under the tenant row filter; redaction of content, findings and the export are delivered by AIFACTORY-US-969, AIFACTORY-US-970 and AIFACTORY-US-967. | ConnectSoft.AI.SoftwareFactory.AuditService |
AIFACTORY-TASK-3871 Audit.Classify resolution from the instance label over the type default to the configured default class |
implementation | The method reads the forwarded tenant under the service scope and resolves the resource of the request to its instance label, else to the default of its type, else to the class of Governance:Classification:DefaultClass, and replies the class, the retention, the rule identifiers and the residency, with the configured default stated as such and carrying no retention and no rule; it writes nothing and resolves no label of another tenant; a request without a resource type is refused with INVALID_ARGUMENT; one resolution routine serves the method, the redaction of AIFACTORY-US-969 and the export of AIFACTORY-US-967. | ConnectSoft.AI.SoftwareFactory.AuditService |
AIFACTORY-TASK-3872 Verify the registry, the resolution and the event through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-AuditService-003\|Scenario=SCN-AuditService-004\|Scenario=SCN-AuditService-008\|Scenario=SCN-AuditService-012)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-968 with the fixture of AIFACTORY-TASK-3859: the label with its rules, its ClassificationChanged record and its entry in one transaction, the rule identifier that two tenants use without touching each other, the 409 for a weaker instance label in both directions, the unchanged call without an event, the 400 and 403 refusals, the list of one tenant with rules, the three resolutions of Audit.Classify with its refusals, and the publication and payload of ClassificationChanged with a transport outage; consumer handling is proven by the suites of ContextBuilderService, ArtifactService, KnowledgeIngestionService, ModelRouterService and StudioBff. |
ConnectSoft.AI.SoftwareFactory.AuditService |
AIFACTORY-US-969: Redact content by the rules of its classification and return the redacted artifact, and redact personal identifiers in evidence past retention while the chain stays verifiable¶
behavior
Redaction is applied in two places, and this PBI delivers both. The first is the method AuditService/Audit.Redact. A service with a workload token that holds the service scope naming AuditService and the forwarded tenant and project names a content reference as artifact-v1, the resource whose label applies and the projection the redacted form is meant for. The service resolves the label of the resource as Audit.Classify does (AIFACTORY-US-968) and takes the rules of that label that apply to the projection. It reads the content through ArtifactService/Artifacts.Fetch, applies each rule with the redactor of the pinned Compliance library that its detector names and with its action, mask, drop or hash, and stores the result through ArtifactService/Artifacts.Store as a new artifact of the same project with a lineage edge to its input. The reply is the artifact-v1 of the redacted artifact with its reference and hash and the identifiers of the rules that were applied. The content is in the memory of the service for the duration of the call and nowhere else: no row, no event, no log record, no activity and no metric of the service holds it (ADR-0019). The store is idempotent on tenant and hash, so the same content redacted by the same rules returns the same artifact and writes nothing new. When no rule of the label applies to the projection, nothing is stored and the reply names the input artifact and states that nothing was redacted. The method fails closed: when a redactor fails, nothing is stored and the call fails, so that content is never returned as redacted when it is not. An artifact that does not exist or belongs to another tenant is answered NOT_FOUND, the answer the artifact store gives (ADR-0015); a call without a workload identity is refused with UNAUTHENTICATED, a token without the service scope with PERMISSION_DENIED and a request without a reference, a resource or a projection with INVALID_ARGUMENT. When ArtifactService does not answer, the call fails fast with UNAVAILABLE and the failure class transient and the service does not retry. The model lists ContextBuilderService as the caller of this method, while that service lists the policy service and not the Audit service among its dependencies; the method is built for any workload with the service scope and proven with a workload of the fixture, and the row is reported with the rows of Audit.Classify. The model also names the artifact store as a dependency of this service while the artifact store does not list this service among its callers, which is reported as well. The second place is evidence itself. The worker RetentionAndRedactionSweeper, hosted by AIFACTORY-US-962 daily, redacts the personal identifiers in the entries of a project that are past the retention window of that project. It removes the actor identifier, a delegating identity and their salts from ActorJson and keeps the digests under which they entered the hash (AIFACTORY-US-964), so entryHash still follows from the stored record and ChainVerifier passes over a redacted entry as before; the mirror never held the identifier. A redacted entry is never redacted twice, under the idempotency key entryId, and no entry is deleted: audit evidence is retained for the period ADR-0019 decision 3 states. Three points the model leaves open are reported to the owner and decided nowhere here. The model names no source for the retention window of a project in this increment, because retention rules arrive with RetentionResidencyService in I4; the window is therefore a setting without a built-in value, and while it is not set the sweeper redacts nothing, which is the safe side of an act that cannot be undone. The worker is also said to enforce the retention of classifications across stores by emitting lifecycle tasks, for which the model names no event and no receiver and lists no output; this delivery emits none, and the retention of a class reaches the other stores through ClassificationChanged. And the handler RedactOnDeletionOrder is built in I4 with RetentionResidencyService and is not registered here.
Acceptance criteria
| AC1 | Given an artifact of a project whose content holds a marker that a rule of its label matches for the projection named, when a workload with the service scope calls AuditService/Audit.Redact, then the content was read once through ArtifactService/Artifacts.Fetch, the redacted content was stored once through ArtifactService/Artifacts.Store as a new artifact of the project with a lineage edge to the input, the reply is its artifact-v1 with reference, hash and the applied rule identifiers, the stored content holds no marker, and the input artifact is unchanged (SCN-AuditService-009). |
| AC2 | Given the same request repeated, then the same redacted artifact is returned and the fake of the artifact store holds one; given a label without a rule for the projection, then nothing is stored and the reply names the input artifact and states that nothing was redacted; and after both, no row, outbox record, log record, activity or metric of the service holds the marker or any other content (SCN-AuditService-009, ADR-0019). |
| AC3 | Given a call to AuditService/Audit.Redact without a workload identity, without the service scope, without a reference, a resource or a projection, for an artifact that does not exist or belongs to another tenant, with a redactor that fails, or while ArtifactService/Artifacts.Fetch or ArtifactService/Artifacts.Store does not answer, when it arrives, then it is refused with UNAUTHENTICATED, PERMISSION_DENIED, INVALID_ARGUMENT and NOT_FOUND, fails without storing anything, or fails fast with UNAVAILABLE and the failure class transient without a repetition by the service (SCN-AuditService-009, ADR-0015). |
| AC4 | Given entries of a project older and younger than the retention window the fixture sets, when RetentionAndRedactionSweeper runs, then the older AuditService/AuditEntry rows hold no actor identifier and no salt and keep their digests, their entryHash still follows from the stored record, the younger entries and the entries of other projects are unchanged, a second run changes nothing, and no entry was deleted; with no window set, a run redacts nothing (model/services/governance/AuditService.yaml). |
| Traces: services | AuditService, ArtifactService |
| Traces: aggregates | AuditService/AuditEntry, AuditService/ClassificationLabel |
| Traces: apis | AuditService/Audit.Redact, ArtifactService/Artifacts.Fetch, ArtifactService/Artifacts.Store |
| Traces: descriptors | artifact-v1 |
| Traces: adrs | ADR-0015, ADR-0019 |
| Traces: requirements | NFR-03, NFR-10 |
| Traces: scenarios | SCN-AuditService-009 |
| Relates: nfrs | NFR-03 |
| Depends on | AIFACTORY-US-961, AIFACTORY-US-962, AIFACTORY-US-963, AIFACTORY-US-964, AIFACTORY-US-968, feature:artifact-service, feature:component-compliance-factory-classifications |
| Sources | model/services/governance/AuditService.yaml, model/scenarios/AuditService.yaml, model/services/knowledge/ArtifactService.yaml, docs/reference/schemas/artifact.schema.json, docs/architecture/data-governance.md#classification, docs/planes/trust-operations/governance/services/audit-service/index.md#workers-and-jobs |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-3873 Audit.Redact over the artifact store with the redactors of the Compliance library |
implementation | The method resolves the label of the resource through the routine of AIFACTORY-TASK-3871, takes its rules for the projection named, reads the content through a typed gRPC client of Artifacts.Fetch, applies each rule with the redactor its detector names and its action, stores the result through Artifacts.Store as a new artifact of the project with a lineage edge to the input and replies its artifact-v1 with the applied rule identifiers; with no applicable rule it stores nothing and names the input; a failing redactor stores nothing and fails the call; the content is held in memory for the call only and written to no row, event, log record, activity or metric; an unknown or foreign artifact is answered NOT_FOUND, an incomplete request INVALID_ARGUMENT and an artifact store that does not answer UNAVAILABLE without a retry. | ConnectSoft.AI.SoftwareFactory.AuditService |
AIFACTORY-TASK-3874 RetentionAndRedactionSweeper redacts personal identifiers of entries past the retention window of their project |
implementation | On its daily schedule the worker selects per tenant the entries of a project that are older than the retention window of the project, a setting without a built-in value that the model gives no source for in this increment, removes the actor identifier, a delegating identity and their salts from ActorJson and keeps their digests, under the idempotency key entryId and with three attempts six hundred seconds apart; entryHash stays valid and the entry is neither deleted nor redacted twice; with no window set nothing is redacted; the worker emits no lifecycle task, because the model names no event and no receiver for one, and no handler of DeletionOrderIssued exists, because RedactOnDeletionOrder is built in I4 with RetentionResidencyService. | ConnectSoft.AI.SoftwareFactory.AuditService |
AIFACTORY-TASK-3875 Verify the redaction of content and of evidence identifiers through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-AuditService-009"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-969 with the fixture of AIFACTORY-TASK-3859: the redacted artifact stored once in the fake of ArtifactService with its lineage edge and without the marker, the repeated request, the label without an applicable rule, the scan of rows, outbox records and telemetry for content, the refusals with their status, the failing redactor that stores nothing, UNAVAILABLE without a retry while the fake does not answer, and the sweep under a moved clock after which the redacted entries still verify through ChainVerifier and no entry is missing. |
ConnectSoft.AI.SoftwareFactory.AuditService |
AIFACTORY-US-970: Raise a finding from evidence, among them an uncertain tool effect that stays unresolved, list the findings of a tenant and resolve one or accept its risk with a reason¶
behavior
A finding is what evidence raises when something needs a person: it names its severity, its category and the evidence entries that justify it. One routine raises it. In one transaction it writes the Finding in the state open with raisedAt and at least one evidence entry and the FindingRaised outbox record, and connectsoft.factory.audit.findings_open rises for the tenant and the severity; while a finding of the same category for the same entries is open, no second one is raised. Three paths of the model use it. Audit.RaiseFindings records the findings a workflow step raises as a findings-v1 document (D133), which AIFACTORY-US-1516 delivers. ChainVerifier raises a Critical finding for a broken chain (AIFACTORY-US-965). The handler RaiseUncertainFinding and a scheduled sweep raise one when the effect of a tool call stays unknown. The handler handles ToolEffectUncertain of ToolAdapterService, the announcement that an effect may have happened and could not be confirmed, idempotently on the event id: it appends one entry of the uncertain effect with the kind ToolEffect and the invocation as target. An uncertain effect is resolved when the Operator decides and the tool service settles the invocation, which arrives as ToolInvoked with the state Observed or Failed and is recorded as evidence. The finding is raised when the sweep runs. The sweep, UncertainEffectSweeper, is hosted like the other scheduled workers of the service. It selects per tenant the entries recorded from ToolEffectUncertain that are older than the window Governance:Audit:UncertainFindingAfterHours, twenty-four hours by default and read when the sweep runs, and for which the chain of the tenant holds no entry recorded from ToolInvoked with the state Observed or Failed for the same invocation. For each it raises a finding in the category of unresolved uncertain effects with the entry of the uncertain effect as its evidence, under the idempotency key of the invocation: an invocation for which a finding of that category exists, open or ended, raises no second one. The service depends on no deferred delivery of a message, a capability neither the Orleans messaging profile of the base template nor a library feature of the backlog states. The model names the handler and no worker for the sweep, so the worker row is reported to the owner as a correction of the model with the values this delivery proposes: the name UncertainEffectSweeper, an hourly schedule read from Governance:Audit:UncertainEffectSweeperSchedule, the fixed retry of three attempts six hundred seconds apart and the two parallel executions partitioned by tenant that the two scheduled workers of the model have, the idempotency key invocationId and FindingRaised as its output. The model also gives AuditEntries no column for the invocation and no index on SourceEvent, so the sweep reads the entries of a tenant through IX_Audit_Tenant_RecordedAt and the invocation from TargetJson, which is reported as well. The severity is an input the model gives for one category only: a broken chain is Critical. The severity of an unresolved uncertain effect is therefore a setting without a built-in value, the service is unready while it is not set, and the open point is reported. The model names two further causes of a finding, a prohibited attempt and an overdue rotation, and no handler, worker or event that raises them; this delivery builds no path for them and reports both. A caller whose token carries factory.audit.read lists the findings of the tenant through AuditService/ListFindings, open and resolved, filtered by severity, category and state, in pages; a finding belongs to its tenant, carries no project, and a finding of another tenant is never listed. A caller whose token carries factory.audit.admin, the Platform admin, ends a finding through AuditService/ResolveFinding with a state, resolved or accepted-risk, and a reason. In one transaction the service moves the open Finding to that state with resolvedAt, writes the FindingResolved outbox record and appends one entry of the resolution with the caller as actor and the reason, because a resolution is itself evidence; findings_open falls. The operation has natural idempotency: a repeated call with the same state answers 200 and changes nothing. A second, different resolution of an ended finding is refused with 409 and a body without a reason or with another state with 400, codes the model omits and AIFACTORY-US-962 reports; an unknown finding and a finding of another tenant are answered 404, the same answer for both (ADR-0015), and a caller without the scope 403. The owner of a finding is set by Audit.RaiseFindings from the document (AIFACTORY-US-1516); the model names the state acknowledged and no operation that sets it, which AIFACTORY-US-961 reports. FindingRaised carries findingId, tenantId, severity and category and is published on audit.findings.v1.finding-raised; AlertRuleService, StudioNotificationService and StudioBff handle it in their own suites. FindingResolved carries findingId, tenantId and state and is published on audit.findings.v1.finding-resolved for StudioBff.
Acceptance criteria
| AC1 | Given ToolAdapterService/ToolEffectUncertain for an invocation and no later ToolAdapterService/ToolInvoked that settles it, when the window Governance:Audit:UncertainFindingAfterHours has passed and the sweep UncertainEffectSweeper runs, then one AuditService/Finding is open with the configured severity, the category of unresolved uncertain effects and the entry of the uncertain effect as its evidence, its AuditService/FindingRaised outbox record was written in the same transaction and connectsoft.factory.audit.findings_open rose; given the settling event arrived before the sweep found the entry past its window, no finding is raised; and the event delivered twice, a second run of the sweep and a run after the finding was ended raise no second finding for the invocation (model/services/governance/AuditService.yaml). |
| AC2 | Given open and ended findings of two tenants with several severities and categories, when AuditService/ListFindings is called by a caller with factory.audit.read with a filter by severity, category and state, then the response is 200 with the matching findings of the tenant of the caller in pages, each with severity, category, evidence entries, state and times, no finding of the other tenant is returned, a caller without the scope is answered 403, and nothing is written (SCN-AuditService-005, ADR-0015). |
| AC3 | Given an open finding and a caller with factory.audit.admin, when AuditService/ResolveFinding is called with the state resolved or accepted-risk and a reason, then the response is 200, the AuditService/Finding holds that state and resolvedAt, the AuditService/FindingResolved outbox record and one entry of the resolution with the caller as actor and the reason were written in the same transaction, and connectsoft.factory.audit.findings_open fell (SCN-AuditService-006). |
| AC4 | Given an ended finding, when AuditService/ResolveFinding is called again with the same state, then the response is 200 and nothing changes; with the other state the response is 409; without a reason or with a state other than resolved and accepted-risk, 400; for an unknown finding or one of another tenant, 404; for a caller without the scope, 403; and no refusal writes or publishes anything (SCN-AuditService-006, ADR-0015). |
| AC5 | Given a finding was raised and later ended, when the outbox dispatcher publishes AuditService/FindingRaised on audit.findings.v1.finding-raised and AuditService/FindingResolved on audit.findings.v1.finding-resolved, then the first is sent in the run event envelope with findingId, tenantId, severity and category and the second with findingId, tenantId and state, neither holds a reason or evidence text, and a transport outage is retried with backoff so neither event is lost or duplicated under its event id (SCN-AuditService-013, SCN-AuditService-014, ADR-0012). |
| Traces: services | AuditService |
| Traces: aggregates | AuditService/Finding, AuditService/AuditEntry |
| Traces: apis | AuditService/ListFindings, AuditService/ResolveFinding |
| Traces: events | AuditService/FindingRaised, AuditService/FindingResolved, ToolAdapterService/ToolEffectUncertain, ToolAdapterService/ToolInvoked |
| Traces: descriptors | run-event-envelope-v1 |
| Traces: adrs | ADR-0012, ADR-0015 |
| Traces: requirements | NFR-04, FUX-05 |
| Traces: scenarios | SCN-AuditService-005, SCN-AuditService-006, SCN-AuditService-013, SCN-AuditService-014 |
| Relates: nfrs | NFR-04 |
| Depends on | AIFACTORY-US-961, AIFACTORY-US-962, AIFACTORY-US-963, AIFACTORY-US-964, feature:tool-adapter-service, feature:contracts-package |
| Sources | model/services/governance/AuditService.yaml, model/scenarios/AuditService.yaml, model/services/tools-mcp/ToolAdapterService.yaml, docs/planes/trust-operations/governance/services/audit-service/index.md#messages, docs/planes/trust-operations/governance/services/audit-service/index.md#options-and-configuration |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-3876 Finding routine, ListFindings and ResolveFinding with the FindingRaised and FindingResolved outbox records |
implementation | One routine raises a finding in the state open with severity, category, at least one evidence entry and raisedAt together with its FindingRaised outbox record in one transaction, raises no second finding of the same category for the same entries while one is open, and moves connectsoft.factory.audit.findings_open; ListFindings returns the findings of the tenant of the caller filtered by severity, category and state in pages through IX_Findings_Tenant_State; ResolveFinding moves an open finding to resolved or accepted-risk with resolvedAt and writes FindingResolved and one entry of the resolution through the append routine of AIFACTORY-TASK-3861 in one transaction, answers 200 without a change for a repeat with the same state, 409 for the other state, 400 without a reason or with another state, 404 for an unknown or foreign finding and 403 for a missing scope; the routine serves ChainVerifier of AIFACTORY-TASK-307, the handler of AIFACTORY-TASK-3877 and Audit.RaiseFindings of AIFACTORY-TASK-6161. | ConnectSoft.AI.SoftwareFactory.AuditService |
AIFACTORY-TASK-3877 RaiseUncertainFinding and the scheduled sweep UncertainEffectSweeper of unresolved uncertain effects |
implementation | The handler of ToolEffectUncertain appends one entry of the uncertain effect with the kind ToolEffect and the invocation as target, idempotently on the event id, and writes no deferred message; the worker UncertainEffectSweeper is hosted like the scheduled workers of AIFACTORY-TASK-236, on an hourly schedule read from Governance:Audit:UncertainEffectSweeperSchedule, with a fixed retry of three attempts six hundred seconds apart, the idempotency key invocationId and at most two parallel executions partitioned by tenant, values this delivery proposes because model/services/governance/AuditService.yaml has no worker row for the sweep, which is reported as a correction of the model; on each run it selects through IX_Audit_Tenant_RecordedAt the entries recorded from ToolEffectUncertain that are older than Governance:Audit:UncertainFindingAfterHours, read when the sweep runs, and have no entry recorded from ToolInvoked with the state Observed or Failed for the same invocation, and raises for each a finding through the routine of AIFACTORY-TASK-3876 in the category of unresolved uncertain effects with the severity of a setting that has no built-in value and keeps the service unready while it is missing; an invocation that already has a finding of that category, open or ended, raises none, so a redelivered event and a repeated run raise one finding; no path is built for a prohibited attempt or an overdue rotation, for which the model names no source. | ConnectSoft.AI.SoftwareFactory.AuditService |
AIFACTORY-TASK-3878 Verify the raised finding, the list, the resolution and the two events through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-AuditService-005\|Scenario=SCN-AuditService-006\|Scenario=SCN-AuditService-013\|Scenario=SCN-AuditService-014)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-970 with the fixture of AIFACTORY-TASK-3859: the finding raised by the sweep from a fixture event of ToolEffectUncertain after the window under a moved clock, none when ToolInvoked settled the invocation before the sweep, the redelivered event, the repeated run and the run after the finding was ended, the unready start without the severity setting, the filtered list of one tenant, the resolution with its FindingResolved record and its entry in one transaction, the repeat, the 409, 400, 404 and 403 answers, and the publication and payload of FindingRaised and FindingResolved with a transport outage; consumer handling is proven by the suites of AlertRuleService, StudioNotificationService and StudioBff. |
ConnectSoft.AI.SoftwareFactory.AuditService |
AIFACTORY-US-1516: Record the findings a workflow step raises as a findings-v1 document, once per finding id, with one audit entry for the call and one FindingRaised per recorded finding¶
behavior
The steps raise-findings of the workflows compliance-check and debt-review end with a list of findings, and these findings get a descriptor of their own and are raised through an operation of AuditService that publishes FindingRaised (D133). The descriptor is findings-v1: a list of findings, each with id, category, severity, owner, evidence references and a redacted summary, and the count critical of the findings of severity critical, which the condition step after raise-findings reads. The operation is the internal gRPC method AuditService/Audit.RaiseFindings, of class shared-write. Its caller is ToolAdapterService, the tool executor, which runs the step and calls the method with its workload token; the token holds the service scope factory.audit.write and forwards the tenant, the project and the run of the step, which the service reads only under that scope (ADR-0015 amendment D114). The service validates the document against docs/reference/schemas/findings.schema.json and checks that critical equals the number of findings of severity critical it lists; a document that fails either check is refused whole with INVALID_ARGUMENT and nothing is recorded. For a valid document the service records, in one transaction, each finding whose id the tenant does not hold yet as an open Finding with its category, its severity, the matching value of FindingSeverity, its owner, its evidence references and its summary, appends through the append routine of AIFACTORY-US-964 one audit entry for the call, which every finding it records names in evidenceEntryIds, and writes one FindingRaised outbox record per recorded finding, through the finding routine of AIFACTORY-US-970, so that connectsoft.factory.audit.findings_open rises. The reply is ack-v1. The finding id is the idempotency key of the step: a finding id already recorded is recorded and published again by no call, so a retried step raises nothing twice, and a call whose findings are all recorded already appends no entry, publishes nothing and answers ack-v1. The summary is redacted by the audit profile of the pinned Compliance library before it is stored and never holds content; evidence is referenced, never copied. A finding of another tenant is never touched, because the id is looked up under the tenant row filter. A call without a workload identity is refused with UNAUTHENTICATED, a token without factory.audit.write with PERMISSION_DENIED, and while audit-sql does not answer the call ends UNAVAILABLE, nothing is recorded and the step retries under its own retry policy. The two workflows belong to I4 and their steps bind no tool for the call yet in model/workflows, so in this delivery the method is proven with a workload shaped like ToolAdapterService; the tool binding of the steps belongs to the workflow and tool features.
Acceptance criteria
| AC1 | Given a workload token that holds factory.audit.write and a valid findings-v1 document of three findings, one of severity critical, with critical equal to one, when AuditService/Audit.RaiseFindings is called, then the reply is ack-v1, three open AuditService/Finding rows hold the category, severity, owner, evidence references and redacted summary of the document, one AuditService/AuditEntry for the call is named in the evidenceEntryIds of each, and three AuditService/FindingRaised outbox records and the AuditService/AuditEntryRecorded record were written in the same transaction (SCN-AuditService-015, docs/reference/schemas/findings.schema.json). |
| AC2 | Given the same document sent again, and a document that repeats two of those ids and adds one new finding, when AuditService/Audit.RaiseFindings is called, then the first call answers ack-v1, appends no entry and publishes nothing, and the second records and publishes only the new finding with one entry for the call, so no finding id is recorded or published twice (SCN-AuditService-015). |
| AC3 | Given a document that fails the schema, one whose critical differs from the findings of severity critical it lists, a call without a workload identity, a token without factory.audit.write, and audit-sql stopped, when AuditService/Audit.RaiseFindings is called, then the answers are INVALID_ARGUMENT, INVALID_ARGUMENT, UNAUTHENTICATED, PERMISSION_DENIED and UNAVAILABLE, and no finding, entry or outbox record is written (SCN-AuditService-015, ADR-0015). |
| AC4 | Given a finding id the tenant of the call does not hold but another tenant does, and a summary that carries a personal identifier, when AuditService/Audit.RaiseFindings records the finding, then a new AuditService/Finding of the tenant of the call is written and the finding of the other tenant is unchanged, the stored summary is redacted, and no summary or evidence text reaches a log record, an activity, a metric or the payload of AuditService/FindingRaised (ADR-0019, model/services/governance/AuditService.yaml). |
| Traces: services | AuditService, ToolAdapterService |
| Traces: aggregates | AuditService/Finding, AuditService/AuditEntry |
| Traces: apis | AuditService/Audit.RaiseFindings |
| Traces: events | AuditService/FindingRaised, AuditService/AuditEntryRecorded |
| Traces: workflows | compliance-check, debt-review |
| Traces: descriptors | findings-v1, ack-v1, run-event-envelope-v1 |
| Traces: adrs | ADR-0012, ADR-0015, ADR-0019 |
| Traces: requirements | FR-06, NFR-04 |
| Traces: scenarios | SCN-AuditService-015 |
| Depends on | AIFACTORY-US-962, AIFACTORY-US-963, AIFACTORY-US-964, AIFACTORY-US-970, feature:contracts-package |
| Sources | model/services/governance/AuditService.yaml, model/scenarios/AuditService.yaml, docs/reference/schemas/findings.schema.json, model/workflows/compliance-check.yaml, model/workflows/debt-review.yaml |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-6161 Audit.RaiseFindings with the findings-v1 validation, the record once per finding id and one audit entry per call |
implementation | Audit.RaiseFindings validates the request against docs/reference/schemas/findings.schema.json and the count critical, records each finding whose id the tenant does not hold as an open Finding with category, severity, owner, evidence references and the redacted summary through the finding routine of AIFACTORY-TASK-3876, appends one audit entry for the call through the append routine of AIFACTORY-TASK-3861 that every recorded finding names in evidenceEntryIds, writes one FindingRaised outbox record per recorded finding in the same transaction and replies ack-v1; a call whose ids are all recorded writes and publishes nothing; the refusals INVALID_ARGUMENT, UNAUTHENTICATED, PERMISSION_DENIED for a token without factory.audit.write and UNAVAILABLE write nothing; the proto takes findings-v1 and is held with golden files. | ConnectSoft.AI.SoftwareFactory.AuditService |
AIFACTORY-TASK-6162 Fixture workload of the tool executor and the findings documents of the acceptance suite |
fixture | The acceptance suite holds a workload identity shaped like ToolAdapterService with a token that holds factory.audit.write, one without it, a valid findings-v1 document of three findings with one critical, a document that repeats two of its ids and adds one, a document that fails the schema, one whose critical count is wrong, one whose summary carries a personal identifier, and a finding id held by a second tenant. | ConnectSoft.AI.SoftwareFactory.AuditService |
AIFACTORY-TASK-6163 Verify Audit.RaiseFindings through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-AuditService-015"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-1516 with the fixture of AIFACTORY-TASK-6162: the recorded findings with one entry and their FindingRaised records in one transaction, the repeated and the partly repeated document, every refusal with the stores and the outbox unchanged, the tenant boundary of a finding id and the redacted summary absent from the telemetry and the event payload. |
ConnectSoft.AI.SoftwareFactory.AuditService |