AIFACTORY-FEAT-060: PolicyEngineService: 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 75 of 185 (Factory code)
PolicyEngineService is the service of bounded context BC-18 (Policy). Central policy — Published policy bundles per scope (platform, tenant, project, where a project may only tighten) that answer who may run which agent with which models against which data with which tools in which environment under which budget, and immutable recorded decisions with effects allow, deny, require-approval or prohibited and obligations (BC-18, original design §43). Its own repository is ConnectSoft.AI.SoftwareFactory.PolicyEngineService.
| Delivers | PolicyEngineService (complete) |
| Stubs | — |
| Realizes | adrs: ADR-0015, ADR-0021, ADR-0022 |
| Requirements | FR-01, FR-04, FR-05, FR-06, FUX-01, FUX-05, NFR-01, NFR-04, XL-04, XL-05, XL-10 |
| Depends on | — |
| Sources | model/services/governance/PolicyEngineService.yaml |
Scenarios to trace (11, catalog): SCN-PolicyEngineService-001 ✓, SCN-PolicyEngineService-002 ✓, SCN-PolicyEngineService-003 ✓, SCN-PolicyEngineService-004 ✓, SCN-PolicyEngineService-005 ✓, SCN-PolicyEngineService-006 ✓, SCN-PolicyEngineService-007 ✓, SCN-PolicyEngineService-008 ✓, SCN-PolicyEngineService-009 ✓, SCN-PolicyEngineService-010 ✓, SCN-PolicyEngineService-011 ✓
AIFACTORY-US-069: PolicyEngineService serves its scope end to end¶
behavior · persona platform-admin
As a platform admin, I want one service that holds the policy bundles of the platform, of each tenant and of each project and records every decision it gives, so that the Policy context has one owner that the rest of the Factory calls through its contract and every gated action is decided in one place.
This is the integration PBI of the feature. PolicyEngineService is the service of bounded context BC-18 and the one place where the Factory decides who may run which agent with which models against which data with which tools in which environment under which budget. It holds policy bundles, one active revision per scope (platform, tenant, project), where a narrower scope may only tighten a wider one (D18), and it records every decision immutably as policy-decision-v1. The repository ConnectSoft.AI.SoftwareFactory.PolicyEngineService is created and scaffolded in I0 by AIFACTORY-TASK-101 of feature repository-and-pipeline-conventions (D140), by the steps of its repository checklist, once from the pinned base template package with UseFactoryProfile (features component-base-template-factory-profile and component-base-template-findings), so 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 service writes its three integration events in the run event envelope of the pinned contracts package (feature contracts-package) through the Orleans outbox of the messaging profile policy-engine, in the transaction of the command that causes them (ADR-0014 amendment D114). The feature is delivered by seven further PBIs: activation and retirement of a bundle revision with the seed of this increment (AIFACTORY-US-916), the platform bundle and the seeded tenant bundle as authored documents with their decision table (AIFACTORY-US-917), Policy.Decide with the recorded decision (AIFACTORY-US-918), the active revision and the tightening check for other services (AIFACTORY-US-919), the reads of bundles (AIFACTORY-US-920), the validation of a project override and the simulation (AIFACTORY-US-921), and the decisions of a run with the retention sweep (AIFACTORY-US-922). This PBI proves that they compose on one deployed instance: the platform bundle is active from the start, the tenant bundle of a tenant is seeded by the service itself at the first decision asked for that tenant, once, idempotently, without an event and without an operator step (D127), the service names the revision a new run pins, a tool call of the first chain is decided, and the decision is recorded and announced. Policy.Decide is the only gate of a tool call for every side-effect class (D123): the outcome allow-with-approval is what asks for an approval, the policy engine opens no approval request, and ToolAdapterService opens it in RunControlService, where approval requests live (D121). In this increment every caller reaches the service inside the cluster over gRPC with a workload token that carries service scopes and no tenant claim; a caller forwards the tenant and the project in the call metadata and the service reads them only under the service scope that names PolicyEngineService (ADR-0015 amendment D114). The five REST operations are reached by a person through the gateway GovernanceHost, which is delivered in I1 like the other gateways (D127), and this feature builds no direct public route. A resource of another tenant is answered 404, over gRPC NOT_FOUND, and a missing scope or right inside the tenant 403 (ADR-0015 amendment D113). Three things of the model arrive later and are stated here so that nothing is assumed. AgentRegistryService is thin in I1: its publication path with AssetReleasePublished arrives in I2 with feature agent-registry-service-publication, and AssetReleaseRevoked and the evaluation gate arrive with its complete delivery in I4 (D140), so in this feature the two inbox handlers of this service are proven against a fixture publisher, and I1 to I3 run on the seeded bundles (D127). ApprovalPolicyService arrives in I4, and no behaviour of this increment depends on it. The handler of DeletionOrderIssued of RetentionResidencyService is built and proven in I4 with that service, and this feature registers none (D121), so of the three consumed events of the model the feature registers two. Telemetry follows ADR-0019: tenant and project on metrics by default, run, step and attempt on activities and log records, and no prompt text, secret, rule document content or payload in a decision, a log record, an activity or a metric.
Acceptance criteria
| AC1 | Given the repository ConnectSoft.AI.SoftwareFactory.PolicyEngineService created and scaffolded in I0 by AIFACTORY-TASK-101 of feature repository-and-pipeline-conventions by the steps of the repository checklist, whose first commit is the unchanged output of dotnet new connectsoft-base -n ConnectSoft.AI.SoftwareFactory.PolicyEngineService --UseFactoryProfile true from the pinned template package, when its pipeline runs with the work of this feature, then no second scaffold was run, the solution builds, the unit and acceptance tests pass with complete reports and a container image is published (ADR-0028, model/services/governance/PolicyEngineService.yaml). |
| AC2 | Given a deployed instance with an empty policy-engine-sql, when the service starts, then the platform bundle is an active PolicyEngineService/PolicyBundle revision with PolicyEngineService/PolicyRevisionActivated written in the transaction of its activation and readiness turned ready only after it; when the first PolicyEngineService/Policy.Decide is asked for a tenant that has no tenant bundle, then the tenant bundle of that tenant is seeded once with the platform revision as its parent, no event is published for the seed and no operator step ran, and PolicyEngineService/Policy.GetActiveRevision names the revision a new run of that tenant pins (ADR-0014, model/services/governance/PolicyEngineService.yaml). |
| AC3 | Given that instance and a workload token that holds the service scope that names PolicyEngineService, when PolicyEngineService/Policy.Decide is asked for a call of the tool propose-change-set and for a call of blueprint-submit-version on a Draft version, then the first answers allow-with-approval and the second allow, each decision is one immutable PolicyEngineService/PolicyDecision with its PolicyEngineService/PolicyDecisionRecorded outbox record in the same transaction, and the service opened no approval request and called RunControlService for none (FR-05, ADR-0022). |
| AC4 | Given a call without a workload identity, a workload token without the service scope and a request that names a revision of another tenant, when a gRPC method of the service is called, then the answers are UNAUTHENTICATED, PERMISSION_DENIED and NOT_FOUND; given a REST call with a token that lacks the scope of the operation and a call for a revision of another tenant, then the answers are 403 and 404; in none of these cases a row, a decision or an outbox record is written (ADR-0015, NFR-01). |
| AC5 | Given decisions of two tenants and two projects, when the telemetry conformance test reads the metrics, activities and log records of the instance, then the four metrics of model/services/governance/PolicyEngineService.yaml are recorded with their modelled dimensions and with tenant and project, activities and log records carry run, step and attempt where the request names them, and no prompt text, secret, rule document content or payload is found in a decision row, a metric, an activity or a log record (ADR-0019, NFR-04). |
| Traces: services | PolicyEngineService, ProjectService, EnvironmentService, AuditService, RunControlService, ToolAdapterService |
| Traces: aggregates | PolicyEngineService/PolicyBundle, PolicyEngineService/PolicyDecision |
| Traces: apis | PolicyEngineService/Policy.Decide, PolicyEngineService/Policy.GetActiveRevision |
| Traces: events | PolicyEngineService/PolicyRevisionActivated, PolicyEngineService/PolicyDecisionRecorded |
| Traces: tools | propose-change-set, blueprint-submit-version |
| Traces: descriptors | policy-decision-request-v1, policy-decision-v1, run-event-envelope-v1 |
| Traces: adrs | ADR-0014, ADR-0015, ADR-0019, ADR-0021, ADR-0022, ADR-0028 |
| Traces: requirements | FR-05, FR-06, NFR-01, NFR-04 |
| Depends on | AIFACTORY-US-916, AIFACTORY-US-917, AIFACTORY-US-918, AIFACTORY-US-919, AIFACTORY-US-920, AIFACTORY-US-921, AIFACTORY-US-922, feature:repository-and-pipeline-conventions, feature:component-base-template-factory-profile, feature:component-base-template-findings, feature:contracts-package, feature:component-observability-factory-conventions, feature:component-compliance-factory-classifications, feature:project-service, feature:environment-service |
| Sources | model/services/governance/PolicyEngineService.yaml, model/backlog/features/governance.yaml, docs/reference/schemas/policy-decision.schema.json, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, docs/planes/trust-operations/governance/services/policy-engine-service/index.md#purpose-and-responsibilities |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-102 Domain model: PolicyBundle with its PolicyRule entities, and PolicyDecision |
implementation | The two aggregates and the PolicyRule entity carry the fields and the invariants of model/services/governance/PolicyEngineService.yaml: a bundle is immutable per revision and is only activated or retired, a narrower scope only tightens a wider one, a Prohibited effect is never overridden, an AllowWithApproval rule names the action class of its approval, and a decision is immutable, names its exact revision and holds hashes and identifiers and never prompt text, secrets or payloads; the enums PolicyScope, PolicyEffect (Allow, AllowWithConstraints, AllowWithApproval, Deny, Prohibited, identical to the outcomes of policy-decision-v1) and PolicyDomain are closed; unit tests cover every invariant, the two transitions of a bundle (activated, retired) and the refusal of any change to a stored revision or decision. | ConnectSoft.AI.SoftwareFactory.PolicyEngineService |
AIFACTORY-TASK-103 Persistence in policy-engine-sql: PolicyBundles, PolicyRules and PolicyDecisions |
migration | Mappings and migrations for the three modelled tables with their tenant columns under the row filter, the index IX_PolicyBundles_Scope_Active on tenant, scope, scope id and active flag, the indexes IX_Decisions_Run and IX_Decisions_Tenant_EvaluatedAt, and the foreign key of PolicyRules to PolicyBundles; the platform bundle of the platform tenant is the one row the filter admits for every tenant, read only; the revision id is a derived key and never a generated one, and the columns ReleaseId and RulesRef, which the model declares not nullable, hold for a seeded bundle the seed marker and the document path AIFACTORY-US-916 states; no column holds prompt text, a secret or a payload; the mapping of PolicyDecisions allows insert and delete and no update; mapping tests run against an isolated test database, never a shared one. | ConnectSoft.AI.SoftwareFactory.PolicyEngineService |
AIFACTORY-TASK-104 API hosting skeleton: REST and gRPC hosts, scope enforcement, problem responses and contract documents for the 5 REST and 3 gRPC operations |
implementation | The five REST routes (ListPolicyBundles, GetPolicyBundle, ValidateProjectPolicy, SimulatePolicy, ListRunDecisions) and the three gRPC methods of the service Policy (Decide, GetActiveRevision, ValidateTightening) are hosted with JWT validation, the scope of each route (factory.policies.read, factory.policies.write, factory.runs.read), problem responses for every modelled refusal code and for the 404 of a resource of another tenant, workload identity and service scope checks on the three gRPC methods, which read the tenant and the project of the call metadata only under the service scope that names PolicyEngineService, and the OpenAPI and proto documents; a REST route admits no workload token; the behaviour of each operation is delivered by AIFACTORY-US-918 to AIFACTORY-US-922, not here. | ConnectSoft.AI.SoftwareFactory.PolicyEngineService |
AIFACTORY-TASK-105 Messaging skeleton: outbox and inbox wiring of the policy-engine profile for 3 published and 2 of the 3 consumed events |
implementation | The outbox writer enlists in the transaction of the commands ActivateRevision and Decide and the dispatcher of the policy-engine messaging profile publishes the three modelled events in the run event envelope of the pinned contracts package (PolicyRevisionActivated, PolicyRevisionRetired, PolicyDecisionRecorded) on their modelled topics; the inbox registers AssetReleasePublished and AssetReleaseRevoked with idempotency on the event id, and DeletionOrderIssued is not registered, because its handler is built in I4 with RetentionResidencyService (D121); what each handler does is delivered by AIFACTORY-US-916. | ConnectSoft.AI.SoftwareFactory.PolicyEngineService |
AIFACTORY-TASK-107 Security, tenancy and telemetry of PolicyEngineService |
implementation | Scopes and roles of the model are enforced, every query is tenant-filtered, a resource of another tenant is answered 404 and NOT_FOUND, the secret messaging-transport comes from its secret reference, and the four metrics of the model (connectsoft.factory.policy.decisions, connectsoft.factory.policy.decision_latency, connectsoft.factory.policy.active_revisions, connectsoft.factory.policy.tightening_rejections) are recorded through the helper of the pinned observability packages with their modelled dimensions and with tenant and project; activities and log records carry run, step and attempt where a request names them, and a conformance test fails when prompt text, a secret, rule document content or a payload reaches a metric, an activity or a log record (ADR-0019). | ConnectSoft.AI.SoftwareFactory.PolicyEngineService |
AIFACTORY-TASK-3691 Deployment values of the service: replica range, options, probes and the addresses of its dependencies |
operations | The deployment manifest of the service states the replica range 3 to 10 of model/services/governance/PolicyEngineService.yaml, the liveness and readiness probes, the options Governance:Policy:DecisionCacheSeconds, Governance:Policy:PlatformSpendThresholdUsd and Governance:Host:FailClosed at the defaults of the model, OrleansMessaging:ServiceName policy-engine, the addresses of ProjectService and EnvironmentService and the store bindings policy-engine-sql, audit-immutable and cache from configuration; readiness reports the store, ProjectService and EnvironmentService and stays unready until the platform bundle is active; the Config Platform and the store binding cache are optional, and each degrades health and never readiness; no rule of this increment references Governance:Policy:PlatformSpendThresholdUsd, which stays bound for the delivery that brings the first caller of a Spend decision; the list of internal projects of the waiver rule is a value the installation passes to the seed, for which the model names no option and the repository fixes no entry; the manifest holds no secret value; the same image runs in the saas-default, hybrid, on-prem and hybrid-compute topologies. | ConnectSoft.AI.SoftwareFactory.PolicyEngineService |
AIFACTORY-TASK-755 Verify policy-engine-service-serves-its-scope by running the declared command |
verification | Run dotnet build -c Release and dotnet test -c Release --filter Category=Acceptance in the pipeline of the repository; a run that discovers no test counts as a failure; the runs pass and prove AC1 to AC5 of AIFACTORY-US-069: the scaffold with the Factory profile, the platform bundle with PolicyEngineService/PolicyRevisionActivated and the tenant bundle seeded at the first decision without an event, the revision named by PolicyEngineService/Policy.GetActiveRevision, the decisions of propose-change-set and of blueprint-submit-version on a Draft version through PolicyEngineService/Policy.Decide with their recorded decisions, the refusals over two tenants, and the telemetry conformance test. |
ConnectSoft.AI.SoftwareFactory.PolicyEngineService |
AIFACTORY-US-916: Activate a policy bundle revision after tightening validation, retire the revision it replaces and announce both¶
behavior · persona platform-admin
As a platform admin, I want a policy bundle to come into force only as a whole revision that tightens its parent, with the revision it replaces retired and both announced, so that new runs pin a revision that never loosens the policy above it and runs that pinned an older revision finish on it.
A policy bundle is the runtime read model of a policy asset: a versioned set of typed rules per domain for one scope, platform, tenant or project, with the revision id runs pin at acceptance. One command of the service changes it, ActivateRevision, and nothing else does: no REST or gRPC operation writes a bundle. The command takes a rule document, the scope it applies to, the release it comes from and the parent revision it tightens. It reads the document into PolicyRule rows, each with rule id, domain, match, effect, obligations and priority, computes rulesHash, and validates the bundle before anything is written. The document is readable, and every rule names a domain of PolicyDomain and an effect of PolicyEffect. A rule with the effect AllowWithApproval names in its obligations the action class the approval must bind to (D21, D127). A tenant bundle only tightens the active platform bundle and a project bundle only tightens the active tenant bundle of its tenant, rule by rule, in the order Allow, AllowWithConstraints, AllowWithApproval, Deny, Prohibited: a narrower rule never has a looser effect than the wider rule that matches the same action, a Prohibited effect is never overridden, and an obligation of the wider rule is never dropped. A valid bundle is written as a new PolicyBundle row with its rules, active true and activatedAt; the revision that was active for the same scope and scope id is set to active false; and the outbox records PolicyRevisionActivated (revision, tenantId, scope, scopeId, rulesHash) and, where a revision was replaced, PolicyRevisionRetired (revision, tenantId, scope) are written in the same transaction. A tenant or project document whose parent scope has no active bundle is refused whole. The revision id is the primary key runs pin, so it is derived and never drawn: a hash, in a fixed text form within the 64 characters of the column, of the tenant, the scope, the scope id, the release id, the parent revision and rulesHash, so that two replicas that handle the same document compute the same key and the primary key of PolicyBundles refuses the second insert, which the command reads as done. A bundle is immutable per revision: the command never changes the rules of a stored revision, an activation whose derived revision id is stored and active changes nothing and publishes nothing, an activation whose id is stored and retired sets that revision active again, retires the one in force and announces both without writing its rules a second time, and a retired revision keeps its rules, because runs that pinned it finish on it. An invalid bundle is refused whole: no row and no event is written, the previous revision stays active (failure mode Rule document unreadable of the model), connectsoft.factory.policy.tightening_rejections counts a refusal for loosening by tenant, and the refusal is logged with the rule ids and without rule content. connectsoft.factory.policy.active_revisions follows every activation and retirement by scope. Three callers reach the command. The first is the startup seed of the platform bundle. When the service starts it activates the platform bundle document that the rule document port serves for the platform scope, under the platform tenant. The tenant bundle is not activated by this command: PolicyEngineService seeds the bundle of a tenant itself, once and idempotently, at the first decision asked for a tenant that has none, with no event and no operator step (D127), and AIFACTORY-US-918 delivers that seed; it reuses the validation, the seed marker and the derived revision id of this PBI, and the platform tenant is seeded the same way at its first decision. The two authored documents are delivered by AIFACTORY-US-917; this PBI proves the seed with fixture documents in the same typed shape, so neither PBI waits for the other. Before the platform document is activated the seed renders into the match of its waiver rule the internal projects the installation supplies (ADR-0021 amendment D83), so the activated rule names them, rulesHash covers them and a changed list is a new revision. The model declares releaseId and rulesRef as required, a published asset release and the artifact reference of the rule document, and a seeded bundle has neither: for a seeded bundle releaseId holds a seed marker with the name and the version of the document and rulesRef the path of the document in the repository of the service with that version, and the mismatch is reported as a correction of the model. The platform seed runs through the command and its validation and is idempotent through the derived revision id: the same document under the same parent gives the same id and changes nothing. When a new platform revision replaces the active one, the tenant bundles keep the parent they were validated against, because the parent is part of the id (AIFACTORY-US-918 states what a decision follows meanwhile). Readiness stays unready until the platform bundle is active, so the service never answers a decision without one. The second and the third caller are the inbox handlers. ActivatePolicyBundle handles AssetReleasePublished of AgentRegistryService for a release of the asset kind Policy and ignores every other kind. RetirePolicyBundle handles AssetReleaseRevoked and retires the revision of the revoked release with PolicyRevisionRetired; a revoked release that no bundle names is ignored. Both are idempotent on the event id through the inbox. What a scope is decided under when its active revision is retired without a successor is not stated by the model: this PBI leaves the scope without an active bundle, so a tenant in that state fails closed like an unseeded one, and the point is reported to the owner. The event of the registry names a release and carries no rule document, and the model lists no dependency through which the service reads the document of a release, so the handler reads it through one rule document port. In this increment the port is bound to the seeded documents of the repository; its binding to a published release is reported to the owner and arrives with the complete registry. AgentRegistryService is thin in I1; it publishes AssetReleasePublished from I2 through the publication path of feature agent-registry-service-publication and AssetReleaseRevoked only in I4 (D140), so in this I1 feature the two handlers are registered and proven against a fixture publisher built from the pinned contracts package. I1 to I3 run on the seeded bundles: until the publication gate of I4 no tenant and no project can activate a bundle of its own, so a tenant cannot drop an approval of its seeded bundle and a project cannot add one (D127). This PBI proves what the publisher of the two events can prove: the outbox record in the transaction of the command, the run event envelope, the payload, and a transport outage retried with backoff without loss or duplicate under the event id (ADR-0012). RunControlService pins the activated revision for new runs and AuditService records the evidence in their own PBIs; StudioBff and ApprovalPolicyService, which also consume the activation, arrive in I3 and I4.
Acceptance criteria
| AC1 | Given an empty policy-engine-sql, the fixture platform and tenant documents of the acceptance suite and a list of internal projects, when the service starts, then one active PolicyEngineService/PolicyBundle of scope Platform exists with its rule rows, its rulesHash, a revision id derived from tenant, scope, scope id, release id, parent revision and rulesHash, the seed marker in releaseId and the document path in rulesRef, its waiver rule names the supplied projects, PolicyEngineService/PolicyRevisionActivated was written to the outbox in the same transaction and readiness turned ready only after it; no tenant bundle is activated at startup, because the first decision of a tenant seeds it (AIFACTORY-US-918); a second start and two replicas that start together change nothing and publish nothing, and a start with a changed list activates a new platform revision and retires the previous one (SCN-PolicyEngineService-009, model/services/governance/PolicyEngineService.yaml). |
| AC2 | Given an active tenant revision and a fixture AssetReleasePublished of the asset kind Policy whose document tightens the platform bundle, when ActivatePolicyBundle handles it, then the new revision is active, the previous one has active false and keeps its rules, and the outbox records PolicyEngineService/PolicyRevisionActivated with revision, tenantId, scope, scopeId and rulesHash and PolicyEngineService/PolicyRevisionRetired with revision, tenantId and scope are written in that one transaction; a redelivery of the event and an event of another asset kind change nothing (SCN-PolicyEngineService-009, SCN-PolicyEngineService-010, ADR-0014). |
| AC3 | Given a document that cannot be read, a rule with an unknown domain or effect, an AllowWithApproval rule without an action class, and a tenant document one of whose rules is looser than the platform rule for the same action, overrides a Prohibited effect or drops an obligation, when an activation is attempted, then each is refused whole, no bundle row, rule row or outbox record is written, the previous revision stays active, a refusal for loosening is counted in connectsoft.factory.policy.tightening_rejections, and the log names the rule ids and no rule content (SCN-PolicyEngineService-009, model/services/governance/PolicyEngineService.yaml). |
| AC4 | Given a fixture AssetReleaseRevoked for the release of an active project revision, when RetirePolicyBundle handles it, then the revision has active false and keeps its rules, PolicyEngineService/PolicyRevisionRetired is written in the same transaction, and a request that names the retired revision as pinned is still decided under it; a revoked release that no bundle names and a redelivered event change nothing (SCN-PolicyEngineService-010, ADR-0014). |
| AC5 | Given outbox records of both events and a transport that is unavailable, when the dispatcher of the policy-engine messaging profile runs, then each event is published on its topic, policy.bundles.v1.policy-revision-activated or policy.bundles.v1.policy-revision-retired, in the run event envelope with its tenant and its payload, the outage is retried with backoff, and no event is lost or published twice under its event id (SCN-PolicyEngineService-009, SCN-PolicyEngineService-010, ADR-0012). |
| Traces: services | PolicyEngineService, AgentRegistryService, RunControlService, AuditService |
| Traces: aggregates | PolicyEngineService/PolicyBundle |
| Traces: events | PolicyEngineService/PolicyRevisionActivated, PolicyEngineService/PolicyRevisionRetired |
| Traces: descriptors | run-event-envelope-v1 |
| Traces: adrs | ADR-0012, ADR-0014, ADR-0015 |
| Traces: requirements | FR-06, NFR-04 |
| Traces: scenarios | SCN-PolicyEngineService-009, SCN-PolicyEngineService-010 |
| Depends on | feature:contracts-package, feature:component-base-template-factory-profile |
| Sources | model/services/governance/PolicyEngineService.yaml, model/services/control-plane/AgentRegistryService.yaml, docs/architecture/adr/0012-messaging-port-and-transport-profiles.md, docs/architecture/adr/0014-run-and-lifecycle-envelopes.md, docs/planes/trust-operations/governance/services/policy-engine-service/index.md#context-and-boundaries |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-3692 ActivateRevision command with the tightening comparer, the two inbox handlers and the rule document port |
implementation | The command reads a rule document into PolicyRule rows, computes rulesHash, derives the revision id as a hash of tenant, scope, scope id, release id, parent revision and rulesHash in a fixed text form within 64 characters, so that two replicas produce the same key, refuses a tenant or project document whose parent scope has no active bundle, validates readability, domains, effects, the action class of every AllowWithApproval rule and, through one tightening comparer that AIFACTORY-US-918, AIFACTORY-US-919 and AIFACTORY-US-921 reuse, the monotonic tightening of a tenant bundle against the active platform bundle and of a project bundle against the active tenant bundle, in the order Allow, AllowWithConstraints, AllowWithApproval, Deny, Prohibited with no Prohibited effect overridden and no obligation dropped; it writes the new revision, sets the replaced revision inactive and writes PolicyRevisionActivated and PolicyRevisionRetired in one transaction, changes nothing when the derived revision id is stored and active, sets a stored retired revision of that id active again without a second write of its rules, and refuses an invalid document whole; ActivatePolicyBundle and RetirePolicyBundle call it from the inbox for a release of the asset kind Policy, idempotent on the event id, and read the document of a release through one rule document port whose binding of this increment serves the seeded documents of the repository; the two metrics active_revisions and tightening_rejections are recorded. | ConnectSoft.AI.SoftwareFactory.PolicyEngineService |
AIFACTORY-TASK-3693 Seed of the platform bundle at startup |
operations | At startup the service host takes the platform bundle document the rule document port serves, renders the internal projects the installation supplies into the match of its waiver rule, so that the activated rule names them and rulesHash covers them, and activates it for the platform scope under the platform tenant through ActivateRevision with the seed marker (name and version of the document) as ReleaseId and the path of the document with its version as RulesRef; the activation is idempotent through the derived revision id, also when replicas start together, and readiness stays unready until the platform bundle is active; a failed seed is retried in the running process with backoff and logged, and liveness keeps answering; no tenant bundle is activated at startup and the host has no seed job, because the tenant bundle is seeded at the first decision of its tenant (AIFACTORY-TASK-3700, D127). | ConnectSoft.AI.SoftwareFactory.PolicyEngineService |
AIFACTORY-TASK-3694 Fixture publisher of the asset release events and the invalid bundle documents of the acceptance suite |
fixture | The acceptance suite holds a publisher that builds AssetReleasePublished and AssetReleaseRevoked in the run event envelope from the pinned contracts package for the asset kind Policy and for another kind, a binding of the rule document port that returns a document per release id and can be made to fail, a fixture platform document with a waiver rule and a fixture seeded tenant document in the typed shape of the model, with which the seed is proven before the authored documents of AIFACTORY-US-917 exist, two lists of internal projects, valid tenant and project documents that tighten their parent, and one invalid document per refusal of AIFACTORY-US-916 (unreadable, unknown domain, unknown effect, AllowWithApproval without an action class, a looser effect, an overridden Prohibited effect, a dropped obligation). | ConnectSoft.AI.SoftwareFactory.PolicyEngineService |
AIFACTORY-TASK-3695 Verify activation and retirement through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-PolicyEngineService-009\|Scenario=SCN-PolicyEngineService-010)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-916 with the fixture documents of AIFACTORY-TASK-3694: the seed at startup with readiness, the derived revision id equal on two replicas, the seed marker and the document path of a seeded bundle, the waiver rule that names the supplied projects and the new platform revision after a changed list, the repeated start that changes nothing, an activation that retires its predecessor in one transaction, every refusal of an invalid document with the stores and the outbox unchanged, the retirement on a revoked release with a pinned decision still served, and the publication of both events with their payloads under a transport outage. |
ConnectSoft.AI.SoftwareFactory.PolicyEngineService |
AIFACTORY-US-917: Author the platform bundle and the seeded tenant bundle as documents and prove their decisions with a decision table¶
enabling · persona platform-admin
As a platform admin, I want the policy of the first increment written as two bundle documents whose decisions are proven case by case, so that every tenant starts with the default approvals, a tenant can later drop them only by changing its own bundle, and the first chain is gated exactly as decided.
Which calls the policy gates is the matter of the policy bundles, and the bundles of the first increment are authored documents of this repository, because the publication path of AgentRegistryService arrives only in I2 (D140) and I1 to I3 run on the seeded bundles (D127). This PBI delivers two documents in the typed shape of the model, scope, parent and rules with id, domain, match, effect, obligations and priority, and the table that proves them. The platform bundle is the ceiling every tenant inherits. For tool calls, domain ToolExecution, it allows every side-effect class: read and sandbox work is autonomous within scope and budget (D21), and it leaves the classes shared-write, production, publication, external and spend allowed (D123, D125), because a tenant bundle may only tighten the platform bundle (D18) and only this reading lets a tenant decide which approvals it keeps. For run acceptance it holds the waiver rule of ADR-0021 amendment D83: a Draft workflow or agent release may run only in the acceptance environment and in the projects the rule names as internal, the decision of such a run records the waiver in its matched rules and its reason, so that the audit entry carries it, and any other run of a Draft release is denied; the rule is removed when the evaluation gate of I4 is delivered. A run acceptance reaches the rule as a request of the action kind run-acceptance, which pairs with the domain RunAcceptance in the one pairing list of the model (D127). The internal projects are an input of the owner. The authored document names none: the seed renders the projects the installation supplies into the match of the waiver rule before it activates the document (AIFACTORY-US-916), so the activated rule names them as decided, rulesHash covers them, the same inputs under one revision give one effect, and a change of the list is a new revision. With an empty list the waiver allows no run. Neither document holds a rule of the domain Spend in this increment. No service of I1 asks a Spend decision, because CostUsageService announces a run above its spend threshold itself and RunControlService opens the spend approval from that event (D117), so a Spend rule would have no caller, no match and no row in the decision table. The option Governance:Policy:PlatformSpendThresholdUsd stays bound for the delivery that brings the first caller, and this is reported to the owner; the Allow rule for a tool call of the class spend is a rule of the domain ToolExecution and stays. The platform bundle also holds the Allow rules without which no step of the first chain proceeds, each named with the caller that asks it: the declared action classes of a workflow definition at load (WorkflowEngineService), model invocation under a seeded model profile (ModelRouterService), the store and the preview of an artifact, the action kinds store and preview of policy-decision-v1 (ArtifactService, D125), retrieval (ContextBuilderService) and approval eligibility for the roles ADR-0015 names, Reviewer and Workspace admin of the project for an approval and Operator for an operator decision (RunControlService). The approval eligibility rules match the action kind approval-eligibility, which pairs with the domain RunAcceptance (D127), with the target approval or operator-decision; the rule id of the eligibility rule for an approval is the approver rule reference a decision of allow-with-approval names. Four more Allow rules are needed outside the first chain, each fixed by a decision. ArtifactService asks Policy.Decide for the export of the artifacts of a project with the action kind export, the target artifact-export and the class external and starts an export for the outcome allow only (model/services/knowledge/ArtifactService.yaml), and the Knowledge gateway of I1 is the route by which a person exports (D125), so without a rule every export of I1 would be answered 403. A tenant takes along what it submitted on request (D31), so the platform bundle holds an Allow rule in the domain DataHandling for that kind and target, for a subject who is Workspace admin of the project or Platform admin, the callers ExportArtifacts admits (D127). SecretBrokerService asks a decision per issuance with the action kind credential-issuance and the purpose of the issuance, and the platform bundle allows the purposes tool-call and sandbox in the domain DataHandling, without which the first outcome cannot issue a credential (D127), and the purpose delivery only for a subject that is the service identity of ConnectorRegistryService or WebhookGatewayService, for the certification of a connector, the delivery reads and the webhook signing secret (D139). IntegrationService asks a decision per grant with the action kind connection-grant, and the platform bundle allows it in the domain ConnectionGrant for a subject who is Workspace admin of the project or the Platform admin (D129). IaCProvisioningService asks a decision per apply with the action kind provisioning-apply and the side-effect class of its plan, and the platform bundle allows it in the domain Deployment (D129). EnvironmentPromotionService, delivered in I2, asks the Policy gate of each promotion with the action kind promotion, which pairs with the domain Deployment, and the class of the target environment, and the platform bundle allows it in that domain for a subject who is Operator or Workspace admin of the project; the rule is authored in this increment so that the bundles in force when promotions start already decide them (D140). The request carries the class of the target environment in action.environment, the environment id in environmentId and the release in action.target. When the subject is a workload acting for a run, the deploy-environment tool through EnvironmentPromotionService/Promotions.Request, the call metadata forwards the requester of the run as delegatedUserId beside the tenant and the project, and the rule checks the role of that delegated user, Operator or Workspace admin of the project, while the decision records the workload as the actor; a workload subject without a delegated user matches no rule and is denied (D127, D141). The seeded tenant bundle is the document PolicyEngineService seeds for a tenant at the first decision asked for it, once and without an event, with the platform revision as its parent (D127, AIFACTORY-US-918). It tightens the platform bundle with the default approvals. A tool call of effective class production, publication, external or spend is answered AllowWithApproval, which Policy.Decide returns as allow-with-approval with the class in obligations.approvalClass and the rule id of the approval eligibility rule in obligations.approverRule, the member obligations of policy-decision-v1; the stored decision keeps the same obligations (D123, D127). A provisioning apply of the class production or external is answered AllowWithApproval the same way, and one of another class keeps the Allow of the platform bundle (D129). A promotion into an environment of the class production is answered AllowWithApproval the same way with the class production, and that approval is the one production approval of the approval gate of the promotion, which EnvironmentPromotionService requests in RunControlService with the revision and the approver rule of the decision, never a second one; a promotion into an environment of another class keeps the Allow of the platform bundle (D133, D140). A call of the tool propose-change-set is answered AllowWithApproval with the class shared-write, returned the same way. A call of blueprint-submit-version for a Draft version is answered Allow, because a Draft blueprint version is autonomous by default (D64). For a shared-write tool other than these two the document holds the default of D21, AllowWithApproval with the class shared-write; the first chain calls no such tool, and this reading is reported to the owner. Only a change of the tenant bundle drops one of these approvals and a project bundle can only add approvals, so the tightening rule holds; I1 to I3 run on the seeded bundles and no path changes a tenant or project bundle before the publication gate of I4 (D127). Neither document holds a threshold, a limit, a quota or a price. An action for which no decision fixes an effect, which today are deletion, the publication of an asset and memory promotion, gets no rule, and Policy.Decide denies an action that no rule of the bundle and its parents matches (D127); a credential issuance for a purpose other than tool-call and sandbox, or of the purpose delivery by a subject other than those two connector services, matches no rule and is denied the same way, and so does a promotion asked for a subject who is neither Operator nor Workspace admin of the project (D140), or for a workload subject whose delegated user holds neither role or that names no delegated user (D141). The proof is a decision table of the acceptance suite: one row per rule and per decided case with subject, action, environment class and expected outcome, evaluated through Policy.Decide against the two documents as the seed activated them. The table also proves the layering: the tenant document passes the tightening validation against the platform document; a copy of it without the production approval passes as well, which is how a tenant drops that approval; a project document that answers Allow for a production tool call under the seeded tenant bundle is refused as loosening; and a project document that gates blueprint drafts passes and turns the decision of blueprint-submit-version into allow-with-approval. The policy engine opens no approval request for any of these outcomes: for a tool call ToolAdapterService opens it in RunControlService (D121).
Acceptance criteria
| AC1 | Given the two documents activated by the seed, when PolicyEngineService/Policy.Decide is asked for a tool call of each side-effect class in the seeded tenant, then read and sandbox answer allow and production, publication, external and spend answer allow-with-approval with the class in obligations.approvalClass and the approval eligibility rule in obligations.approverRule, each reply valid against docs/reference/schemas/policy-decision.schema.json; and when the same four calls are evaluated against the platform document alone, then each answers allow, as model/services/governance/PolicyEngineService.yaml states for the two bundles (FR-05). |
| AC2 | Given the seeded tenant, when PolicyEngineService/Policy.Decide is asked for a call of the tool propose-change-set and for a call of blueprint-submit-version on a Draft version, then the first answers allow-with-approval with obligations.approvalClass naming shared-write and obligations.approverRule naming the approval eligibility rule, and the second allow; given a project bundle that gates blueprint drafts, then the second answers allow-with-approval; in no case the service opens an approval request (ADR-0022, XL-10). |
| AC3 | Given a Draft workflow release and a platform revision whose waiver rule names the internal projects the installation supplied, when PolicyEngineService/Policy.Decide is asked for a run acceptance, a request of the action kind run-acceptance whose decision names the domain RunAcceptance, in the acceptance environment and in a named project, then the outcome is allow and the matched rules and the reason of the decision name the waiver; given the same release in another environment or in a project the rule does not name, then the outcome is deny; the repository fixes no project, the activated rule names the projects the installation supplied, and a changed list gives a new revision with a new rulesHash (ADR-0021). |
| AC4 | Given the two documents, when the tightening comparer checks them, then the tenant document passes against the platform document and so does a copy of it without the production approval; a project document that answers Allow for a production tool call under the seeded tenant bundle is refused as loosening with the rule named, and a project document that adds an approval passes, so that PolicyEngineService/PolicyBundle revisions keep the layering of ADR-0015; and a document test fails when either authored document holds a threshold, a limit, a quota, a price or a project id, when it holds a rule of the domain Spend, when a rule of either document has no row in the decision table, or when a rule names an action kind outside docs/reference/schemas/policy-decision.schema.json. |
| AC5 | Given the seeded tenant, when PolicyEngineService/Policy.Decide is asked for the action kind export with the target artifact-export by a Workspace admin of the project, by the Platform admin and by a member with neither role, then the outcomes are allow, allow and deny, as ExportArtifacts of model/services/knowledge/ArtifactService.yaml needs, and the same three subjects asking the action kind connection-grant are answered allow, allow and deny in the domain ConnectionGrant; when it is asked for the action kind credential-issuance, then the purposes tool-call and sandbox answer allow in the domain DataHandling, the purpose delivery answers allow for the service identities of ConnectorRegistryService and WebhookGatewayService and deny for any other subject (D139), and any other purpose deny; when it is asked for the action kind provisioning-apply, then the class sandbox answers allow and the classes production and external answer allow-with-approval in the domain Deployment; when it is asked for the action kind promotion with the class of the target environment, then an Operator and a Workspace admin of the project are answered allow for the classes development, test and staging and allow-with-approval with obligations.approvalClass production for the class production, and a member with neither role deny, each in the domain Deployment (D140); a workload subject whose delegatedUserId names an Operator or a Workspace admin of the project is answered the same as that user with the workload recorded as the actor of the decision, and a workload subject whose delegated user holds neither role or that names no delegated user deny (D141); when it is asked for the action kind approval-eligibility, then a Reviewer and a Workspace admin of the project are answered allow for the target approval, an Operator for the target operator-decision, and every other role deny, each in the domain RunAcceptance; and an action no rule of the chain matches, such as a deletion, is answered deny with the reason that no rule matched (ADR-0015, model/services/governance/PolicyEngineService.yaml). |
| Traces: services | PolicyEngineService, ToolAdapterService, RunControlService, ArtifactService, SecretBrokerService, IntegrationService, IaCProvisioningService, EnvironmentPromotionService |
| Traces: aggregates | PolicyEngineService/PolicyBundle |
| Traces: apis | PolicyEngineService/Policy.Decide |
| Traces: tools | propose-change-set, blueprint-submit-version |
| Traces: descriptors | policy-decision-request-v1, policy-decision-v1 |
| Traces: adrs | ADR-0015, ADR-0021, ADR-0022 |
| Traces: requirements | FR-05, FR-06, XL-10 |
| Depends on | AIFACTORY-US-916, AIFACTORY-US-918 |
| Sources | model/services/governance/PolicyEngineService.yaml, docs/reference/schemas/policy-decision.schema.json, docs/architecture/adr/0021-quality-gates.md, docs/planes/control/approvals.md, docs/planes/capability-tools/tool-policies.md, model/services/knowledge/ArtifactService.yaml, model/tools/propose-change-set.yaml, model/tools/blueprint-submit-version.yaml |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-3696 Platform bundle document of the first increment |
contract | The repository holds the platform bundle as one versioned document in the typed shape of the model, with scope Platform and no parent: for the domain ToolExecution one Allow rule per side-effect class read, sandbox, shared-write, production, publication, external and spend (D21, D123, D125); for RunAcceptance the waiver rule of AIFACTORY-TASK-343 and its deny rule, which match the action kind run-acceptance, and the approval eligibility rules, which match the action kind approval-eligibility and allow a Reviewer and a Workspace admin of the project for the target approval and an Operator of the project for the target operator-decision, the rule id of the first being the approver rule reference of an allow-with-approval decision; the Allow rules of the first chain for the declared action classes of a workflow definition, model invocation under a seeded model profile, the action kinds store and preview and retrieval; and in DataHandling one Allow rule for the action kind export with the target artifact-export for a subject who is Workspace admin of the project or Platform admin, which cites D31, D127 and model/services/knowledge/ArtifactService.yaml, and one Allow rule for the action kind credential-issuance with the purposes tool-call and sandbox (D127) and one for the purpose delivery whose subject is the service identity of ConnectorRegistryService or WebhookGatewayService (D139); in ConnectionGrant one Allow rule for the action kind connection-grant for a subject who is Workspace admin of the project or Platform admin (D129); in Deployment one Allow rule for the action kind provisioning-apply (D129) and one Allow rule for the action kind promotion for a subject who is Operator or Workspace admin of the project (D140), which for a workload subject matches the role of the delegated user named by delegatedUserId, records the workload as the actor and matches no workload subject without a delegated user (D127, D141); the document holds no rule of the domain Spend, because no service of this increment asks a Spend decision, and no rule for deletion, the publication of an asset or memory promotion, which are therefore denied as unmatched; it holds no threshold, limit, quota, price or project id, and each rule carries the decision that fixes it in its id or its comment. | ConnectSoft.AI.SoftwareFactory.PolicyEngineService |
AIFACTORY-TASK-3697 Seeded tenant bundle document of the first increment |
contract | The repository holds the seeded tenant bundle as one versioned document with scope Tenant and the platform revision as parent, the document the service seeds for a tenant at its first decision (D127): AllowWithApproval, with the action class and the reference of the approval eligibility rule of the platform document named in the obligations, for a tool call of effective class production, publication, external or spend (D123, D125), for a provisioning apply of the class production or external (D129) and for a promotion into an environment of the class production, whose approval is the one production approval of the approval gate of the promotion (D133, D140); AllowWithApproval with the class shared-write for the tool propose-change-set and, as the default of D21, for every other shared-write tool; and, with a higher priority, Allow for the tool blueprint-submit-version on a Draft version (D64); the document adds nothing else, holds no threshold, limit, quota or price, and passes the tightening comparer against the platform bundle document. | ConnectSoft.AI.SoftwareFactory.PolicyEngineService |
AIFACTORY-TASK-343 Waiver rule for Draft releases before the evaluation gate exists |
implementation | The platform bundle document holds one RunAcceptance rule that allows a Draft workflow or agent release to run only in the acceptance environment and in the projects its match names as internal, and one that denies every other run of a Draft release; the authored document names no project and marks the place in the match of the rule into which the seed of AIFACTORY-TASK-3693 renders the projects the installation supplies before activation, so the activated rule names them, rulesHash covers them, one revision gives one effect for the same inputs and a changed list is a new revision; with an empty list the rule allows no run; a decision under the waiver names the waiver rule in its matched rules and its reason, so that the policy decision and the audit entry AuditService records from PolicyDecisionRecorded both carry it (decision D83, docs/architecture/adr/0021-quality-gates.md); the rule is marked for removal with the evaluation gate of I4. | ConnectSoft.AI.SoftwareFactory.PolicyEngineService |
AIFACTORY-TASK-3698 Verify the two bundle documents with the decision table |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Feature=SeededBundles"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-917 from one decision table file of the suite, evaluated through PolicyEngineService/Policy.Decide against the documents as the seed activated them: the seven side-effect classes of a tool call under the tenant bundle and under the platform bundle alone, propose-change-set with obligations.approvalClass and obligations.approverRule of its reply, blueprint-submit-version on a Draft version with and without a project bundle that gates drafts, the run acceptance request of the action kind run-acceptance under the waiver with its two denials and under a changed list of internal projects, the approval eligibility request of the action kind approval-eligibility for a Reviewer, a Workspace admin, an Operator and a role without eligibility, the export and the connection-grant requests for a Workspace admin, a Platform admin and a member with neither role, the credential-issuance request for the purposes tool-call, sandbox and another purpose and for the purpose delivery by the two connector service identities and by another subject, the provisioning-apply request for the classes sandbox, production and external, the promotion request for the classes development, test, staging and production by an Operator, a Workspace admin and a member with neither role, and by a workload subject whose delegated user is an Operator, a Workspace admin or neither and by one without a delegated user (D141), the four layering cases of the tightening comparer, the deny of an unmatched action, and the document test for amounts, project ids, a rule of the domain Spend, uncovered rules and unknown action kinds. |
ConnectSoft.AI.SoftwareFactory.PolicyEngineService |
AIFACTORY-US-918: Decide a subject, an action and a resource under the pinned or the active revision and record the decision¶
behavior · persona reviewer
As a reviewer, I want every gated action of a run decided by one evaluation under the policy revision the run pinned, with the decision recorded as it was given, so that I can see afterwards which rule allowed, gated or denied an action and no service decides a gate on its own.
Policy.Decide is the one evaluation of the Factory and the only gate of a tool call for every side-effect class (D123). Its callers are services: RunControlService at acceptance and for the approver rule of an approval, WorkflowEngineService when it loads a definition, AgentRuntimeService before a gated call, ModelRouterService per route plan and per invocation, ToolAdapterService per tool call and ArtifactService for a store, a preview and an export; ContextBuilderService, IntegrationService and MemoryPromotionService call it as their deliveries reach it. A caller presents a workload token that carries service scopes and no tenant claim and forwards the tenant and the project in the call metadata, which the service reads only when the token holds the service scope that names PolicyEngineService (ADR-0015 amendment D114); in this increment the call arrives inside the cluster. The gateway GovernanceHost, delivered in I1 like the other gateways (D127), also routes internal gRPC calls to this method, but the callers of I1 keep the in-cluster address they were delivered with; no feature of the backlog switches them to the gateway, which would be a deployment value of each caller, and the point is reported to the owner. The request is policy-decision-request-v1 (docs/reference/schemas/policy-decision-request.schema.json) and the reply the recorded policy-decision-v1 (D127). The request carries the subject (caller id, caller kind, delegated user, tenant, project, agent, roles), the action (kind, target, sideEffectClass, classification, environment, purpose), the resource, the run, the environment, an inputs hash and an optional policyRevision, and it names no domain. The values of classification are the Factory data classes of the pinned compliance library (feature component-compliance-factory-classifications), and the service defines none of its own. Each of the sixteen action kinds of the schema pairs with exactly one value of PolicyDomain, and the PolicyDecision invariant of the model is the one place of that pairing: run-acceptance and approval-eligibility with RunAcceptance, model-invocation with ModelAccess, tool-invocation with ToolExecution, retrieval with KnowledgeAccess, memory-promotion with MemoryPromotion, connection-grant with ConnectionGrant, publication, provisioning-apply and promotion with Deployment, spend with Spend, and export, deletion, store, preview and credential-issuance with DataHandling (D127, D129, D140). The repository holds that pairing as one table that a contract test compares with the model, and the decision records the domain of its kind in domain; a caller never supplies one. RunControlService asks a run acceptance with the kind run-acceptance and the eligibility of a decider with the kind approval-eligibility and the target approval or operator-decision; SecretBrokerService asks credential-issuance with the purpose of the issuance, IntegrationService connection-grant, IaCProvisioningService provisioning-apply with the side-effect class of its plan, and EnvironmentPromotionService, from I2, promotion with the class of the target environment in action.environment, the environment id in environmentId, the release in action.target and, for a promotion a run requested, the workload as subject with the requester of the run as delegatedUserId (D140, D141). The service evaluates in a fixed order. When the tenant of the request has no tenant bundle, the service first seeds it, once and idempotently: it validates the seeded tenant document of AIFACTORY-US-917 against the active platform revision with the comparer of AIFACTORY-US-916 and writes it as the active tenant bundle with the platform revision as its parent and a revision id derived from the tenant, the scope and the release, so that a concurrent first decision on another replica meets the primary key and reads the stored bundle; the seed publishes no event and needs no operator step (D127). The platform tenant is seeded the same way at its first decision. It then resolves the revision: the policyRevision the request names, which is the revision the run pinned and may be retired, or else the active revision of the scope; a named revision that the tenant does not hold is answered NOT_FOUND. From that revision it follows the stored parentRevision to the tenant bundle and the platform bundle, for a pinned and for an active revision alike, so a decision under one revision is reproducible. This is the interim rule for a case the model leaves open: when a wider scope activates a newer revision, the active bundles below it keep the parent they were validated against, their decisions follow that stored parent, and the rules of the newer wider revision reach a scope only when its own bundle is activated again under the new parent. What the activation of a tenant or platform revision must do to the active bundles below it is reported to the owner. It reads the roles and the delegated scope of the subject through Projects.ResolveScope of ProjectService when the request does not carry them, and the class of the environment the action names through Environments.GetPolicyClass of EnvironmentService, and raises the side-effect class of the action by that class and never lowers it; the raised class is the actionClass of the decision. In each bundle of the chain the matching rule of the highest priority gives the effect of that bundle, and across the chain the strictest effect decides, in the order Prohibited, Deny, AllowWithApproval, AllowWithConstraints, Allow, which is what tightening means at decision time; an action that no rule of the bundle and its parents matches is denied (D127). The service then writes one immutable PolicyDecision with tenant, project, environment, run, subject, domain, action, action class, resource, inputs hash, revision, effect, obligations, matched rules, reasons and evaluatedAt, and the PolicyDecisionRecorded outbox record with decisionId, tenantId, runId, domain, action, actionClass, effect and policyRevision, in one transaction, and replies. The five values of PolicyEffect are the five outcomes of the schema, one to one (D127): Allow is allow, AllowWithConstraints is allow-with-constraints with its constraints listed, AllowWithApproval is allow-with-approval, Deny is deny and Prohibited is prohibited, which no approval can override. A decision of AllowWithApproval names in its obligations the action class the approval must bind to and the reference of the approval rule, and the approval that follows binds to this decision id. The reply returns the obligations of the matched rules in the member obligations of policy-decision-v1: approvalClass and approverRule for an approval, the further terms an approval rule states (approver roles, quorum, expiry, re-requests, author exclusion, break glass), redactions, limits and logging, and action.sideEffectClass holds the raised class; the stored PolicyDecision keeps the same obligations. RunControlService reads the approval rule of a request from obligations.approverRule and asks the eligibility of a decider with a request of the kind approval-eligibility. The policy engine opens no approval request and calls RunControlService for none: for a tool call ToolAdapterService opens the request in RunControlService, where approval requests live (D121). A decision never contains prompt text, secrets or payloads: the request has no member for arguments or content, only for their hash, and the decision holds identifiers, classes, rule ids and hashes. The same inputs under the same revision give the same effect. Governance:Policy:DecisionCacheSeconds caches a decision per revision and never across revisions: a repeat of the same request, with the same subject, action, resource, run and inputs hash, within that time returns the recorded decision with its decision id and writes no second row and no second event, so a caller that retries after a lost reply within that time, with the cache reachable, receives the one decision. The cache is the store binding cache of the model and never the authority: when it does not answer, or the entry has ended, the request is evaluated and recorded anew with a new decision id and its own event, with the same effect, because evaluation is deterministic; health reports the cache degraded and readiness does not depend on it. A call without a workload identity is refused with UNAUTHENTICATED; a workload token without the service scope, and a user token, with PERMISSION_DENIED; a request without a subject, an action kind or a tenant, or with an unknown action kind, with INVALID_ARGUMENT; in each case nothing is recorded and no bundle is seeded. The service fails closed (Governance:Host:FailClosed): when ProjectService, EnvironmentService or policy-engine-sql does not answer the call ends UNAVAILABLE, and when the tenant holds a tenant bundle but none is active, because its revision was retired without a successor, it ends FAILED_PRECONDITION; no decision is recorded, no outcome is returned and the caller treats the action as not allowed. The service retries no call on its own. The Config Platform is an optional dependency: when it does not answer, the service keeps deciding from the bundles it holds and health reports it degraded. The service records connectsoft.factory.policy.decisions by tenant, domain and effect and connectsoft.factory.policy.decision_latency by domain, the series the objective of the model, 50 ms at p95, is measured against once the system is deployed; no value is claimed here. This PBI proves what the publisher of PolicyDecisionRecorded can prove: the outbox record in the transaction of the decision, the run event envelope, the payload and a transport outage retried without loss or duplicate. AuditService, the one consumer of the event, records the evidence in its own PBIs.
Acceptance criteria
| AC1 | Given active bundles of the platform and of a tenant and a workload token that holds the service scope that names PolicyEngineService, when PolicyEngineService/Policy.Decide is called with a policy-decision-request-v1 for a tool call with the tenant and the project in the call metadata, then the reply is a policy-decision-v1 document with decisionId, policyRevision, subject, action, domain, outcome, matchedRules, reason, evaluatedAt and evaluator, the domain being the one its action kind pairs with, one immutable PolicyEngineService/PolicyDecision row holds the same decision with its domain, action class and inputs hash, and the PolicyEngineService/PolicyDecisionRecorded outbox record is written in the same transaction; given a tenant that has no tenant bundle, then its first decision, also when two replicas receive it together, seeds one active tenant bundle with the platform revision as parent before it is evaluated, writes no outbox record for the seed and needs no operator step (SCN-PolicyEngineService-006, SCN-PolicyEngineService-011, ADR-0014). |
| AC2 | Given a request that names a retired revision a run pinned and an environment whose class EnvironmentService/Environments.GetPolicyClass returns as Production, when PolicyEngineService/Policy.Decide is called, then the decision is evaluated under the pinned revision and its parents and not under the active one, the actionClass of the decision is raised to production and never lowered, the roles of a subject the request does not carry were read through ProjectService/Projects.ResolveScope, and the effects Allow, AllowWithConstraints, AllowWithApproval, Deny and Prohibited are returned as allow, allow-with-constraints, allow-with-approval, deny and prohibited; the reply of allow-with-approval carries the raised class in action.sideEffectClass and in obligations.approvalClass and the approval rule in obligations.approverRule, the stored decision holds the same obligations, an action no rule matches is answered deny, and every reply is valid against docs/reference/schemas/policy-decision.schema.json (SCN-PolicyEngineService-006, FR-05). |
| AC3 | Given the same request repeated within Governance:Policy:DecisionCacheSeconds, when PolicyEngineService/Policy.Decide is called again, then the reply carries the decision id of the first call and no second row or outbox record exists; given the cache stopped or the entry ended, then the request is evaluated and recorded anew with a new decision id and the same effect, health reports the cache degraded and readiness stays ready; given a newer revision became active for the scope in between, then a request that names no revision is evaluated anew under the new revision; and no decision row, event, log record, activity or metric holds prompt text, a secret or a payload (SCN-PolicyEngineService-006, ADR-0019). |
| AC4 | Given a call without a workload identity, a workload token without the service scope or a user token, a request without a subject or with an unknown action kind, a named revision of another tenant, a tenant whose tenant revision was retired without a successor, and ProjectService, EnvironmentService or policy-engine-sql stopped, when PolicyEngineService/Policy.Decide is called, then the answers are UNAUTHENTICATED, PERMISSION_DENIED, INVALID_ARGUMENT, NOT_FOUND, FAILED_PRECONDITION and UNAVAILABLE respectively, no PolicyEngineService/PolicyDecision is written, nothing is published and the service retried nothing (SCN-PolicyEngineService-006, ADR-0015). |
| AC5 | Given the outbox record of a decision and a transport that is unavailable, when the dispatcher of the policy-engine messaging profile runs, then PolicyEngineService/PolicyDecisionRecorded is published on policy.decisions.v1.policy-decision-recorded in the run event envelope with decisionId, tenantId, runId, domain, action, actionClass, effect and policyRevision, the outage is retried with backoff, and the event is neither lost nor published twice under its event id (SCN-PolicyEngineService-011, ADR-0012). |
| Traces: services | PolicyEngineService, ProjectService, EnvironmentService, AuditService, ToolAdapterService, RunControlService |
| Traces: aggregates | PolicyEngineService/PolicyDecision, PolicyEngineService/PolicyBundle |
| Traces: apis | PolicyEngineService/Policy.Decide, ProjectService/Projects.ResolveScope, EnvironmentService/Environments.GetPolicyClass |
| Traces: events | PolicyEngineService/PolicyDecisionRecorded |
| Traces: descriptors | policy-decision-request-v1, policy-decision-v1, run-event-envelope-v1 |
| Traces: adrs | ADR-0012, ADR-0014, ADR-0015, ADR-0019, ADR-0022 |
| Traces: requirements | FR-04, FR-05, NFR-04, XL-04 |
| Traces: scenarios | SCN-PolicyEngineService-006, SCN-PolicyEngineService-011 |
| Depends on | AIFACTORY-US-916, feature:project-service, feature:environment-service, feature:contracts-package, feature:component-observability-factory-conventions, feature:component-compliance-factory-classifications |
| Sources | model/services/governance/PolicyEngineService.yaml, docs/reference/schemas/policy-decision.schema.json, docs/reference/schemas/policy-decision-request.schema.json, model/services/control-plane/ProjectService.yaml, model/services/control-plane/EnvironmentService.yaml, docs/architecture/adr/0019-data-governance.md, docs/planes/trust-operations/governance/services/policy-engine-service/index.md#sagas-and-long-running-flows |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-3699 Proto of the Policy service, the kind to domain pairing table and the contract test of the request and the reply |
contract | The proto of the gRPC service Policy fixes the request message of Decide as policy-decision-request-v1 (subject with caller id, caller kind, delegated user, tenant, project, agent and roles; action with kind, target, sideEffectClass, classification, environment and purpose; resource, run, environment, inputs hash, optional policyRevision) with no member for a domain, arguments or content, and its reply message as the policy-decision-v1 document with its members domain and obligations; one pairing table of the repository pairs each of the sixteen action kinds, promotion with Deployment among them, with exactly one PolicyDomain value as the PolicyDecision invariant of model/services/governance/PolicyEngineService.yaml states it (D127, D129, D140); a contract test validates every request and every reply of the suite against docs/reference/schemas/policy-decision-request.schema.json and docs/reference/schemas/policy-decision.schema.json, holds the proto with golden files, and fails when the schema gains an action kind the table does not list or the table differs from the invariant of the model. | ConnectSoft.AI.SoftwareFactory.PolicyEngineService |
AIFACTORY-TASK-3700 Evaluation and recording of a decision in Policy.Decide |
implementation | Policy.Decide first seeds the tenant bundle of a tenant that has none, once and idempotently with a revision id derived from tenant, scope and release, validated by the tightening comparer of AIFACTORY-TASK-3692 against the active platform revision and written without an outbox record, so that two replicas that receive a first decision together seed one bundle (D127); it resolves the named or the active revision and its parents through the stored parentRevision, also when a wider scope has activated a newer revision since, derives the domain from the pairing table, reads missing roles through a typed client of Projects.ResolveScope and the environment class through a typed client of Environments.GetPolicyClass, raises the action class and never lowers it, takes in each bundle the matching rule of the highest priority and across the chain the strictest effect, denies an unmatched action, writes the immutable PolicyDecision and the PolicyDecisionRecorded outbox record in one transaction and returns the effect as the outcome of the same name, with the obligations of the matched rules in the member obligations of the reply, approvalClass and approverRule for an AllowWithApproval decision; within Governance:Policy:DecisionCacheSeconds a repeat of the same request under the same revision returns the recorded decision and writes nothing, and the cache is keyed by revision; when the store binding cache does not answer or the entry has ended the request is evaluated and recorded anew with a new decision id, health reports the cache degraded and readiness does not depend on it; the refusals UNAUTHENTICATED, PERMISSION_DENIED, INVALID_ARGUMENT, NOT_FOUND, FAILED_PRECONDITION and UNAVAILABLE record nothing; the metrics decisions and decision_latency are recorded; no call is retried by the service. | ConnectSoft.AI.SoftwareFactory.PolicyEngineService |
AIFACTORY-TASK-3701 Fakes of ProjectService and EnvironmentService, the two-tenant bundle fixture and the token matrix of the acceptance suite |
fixture | The acceptance suite holds a fake of Projects.ResolveScope that returns roles and delegated scope per subject and can be stopped, a fake of Environments.GetPolicyClass that returns each environment class and can be stopped, bundles of the platform, of two tenants and of two projects with one retired revision, a tenant without a tenant bundle, a switch that fails the transaction of policy-engine-sql, a switch that stops the cache, and tokens for the matrix: no token, a workload token with and without the service scope that names PolicyEngineService, and user tokens of each role, of two tenants and with a role in one project and none in another. | ConnectSoft.AI.SoftwareFactory.PolicyEngineService |
AIFACTORY-TASK-3702 Verify Policy.Decide and the publication of its event through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-PolicyEngineService-006\|Scenario=SCN-PolicyEngineService-011)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-918 with the fixtures of AIFACTORY-TASK-3701: a recorded decision with its outbox record and its paired domain, the seed of a tenant bundle at the first decision of a tenant on two replicas without an outbox record, a decision under a pinned retired revision, the raised action class, the five effects returned as the five outcomes, the deny of an unmatched action, obligations.approvalClass and obligations.approverRule of an allow-with-approval reply and the validity of request and reply against their schemas, the cached repeat with one decision id, the repeat with the cache stopped and after the entry ended, every refusal with the store and the outbox unchanged, the fail-closed answers while a dependency is stopped, a scan of the rows, the events and the captured telemetry for content, and the publication of PolicyEngineService/PolicyDecisionRecorded under a transport outage. |
ConnectSoft.AI.SoftwareFactory.PolicyEngineService |
AIFACTORY-US-919: Name the revision a new run pins for its scope and check that a candidate bundle only tightens its parent¶
behavior · persona platform-admin
As a platform admin, I want run control to ask which policy revision a new run pins and the asset registry to ask whether a candidate policy only tightens its parent, so that every run is pinned to one exact revision and no policy that loosens the one above it is ever published.
Two internal gRPC methods serve other services and write nothing. Policy.GetActiveRevision answers RunControlService, which pins a policy revision on every run at acceptance. For the scope of an execution-scope-v1 request, a tenant with or without a project, it returns the revision a new run of that scope must pin: the active revision of the narrowest scope that has a bundle, the project bundle where the project has one and else the tenant bundle, together with the scope of that bundle, its rulesHash and the revisions of its parents up to the platform bundle. The parents are the stored ones, as for a decision (AIFACTORY-US-918): when the tenant has activated a newer revision since a project bundle was activated, the reply for that project still names the project revision with the tenant revision it was validated against, so runs of that project are not yet decided under the newer tenant rules until the project bundle is activated again; the model does not say what a new tenant revision does to the active project revisions of the tenant, and the point is reported to the owner. A seeded tenant bundle publishes no event (D127), so RunControlService learns its revision from this method and not from the event. For a tenant that has no tenant bundle yet the method runs the same seed as the first decision (AIFACTORY-US-918), once and idempotently and without an event, before it answers, so that a first run of a tenant pins the seeded revision whichever of the two calls RunControlService makes first; this reading is reported to the owner. The platform tenant is treated the same way. The model names policy-decision-v1 as the reply descriptor of this method although the method records no decision and returns no outcome; the proto of this feature fixes a reply message with those members, and the descriptor is reported as a correction of the model. RunControlService also hears PolicyRevisionActivated and keeps the activated revision for new runs through its handler PinActivePolicyRevision; the method is the answer for a scope it has not heard of yet, and both name the same revision. A tenant that holds a tenant bundle but none active, because its revision was retired without a successor, is answered FAILED_PRECONDITION, so no run is accepted under the platform bundle alone and without the default approvals of the seeded tenant bundle. Policy.ValidateTightening answers the publication of policy assets: before AgentRegistryService publishes a release of the asset kind Policy it asks whether the candidate bundle only tightens its parent. The request carries the candidate document, its scope and its scope id. The service resolves the parent, the active platform bundle for a tenant candidate and the active tenant bundle for a project candidate. A candidate whose parent scope has no active bundle, which is a project candidate of a tenant without an active tenant bundle, is answered FAILED_PRECONDITION, nothing is written, and the registry publishes no policy release for it. For a candidate with a parent the service runs the comparison the activation runs (AIFACTORY-US-916): rule by rule in the order Allow, AllowWithConstraints, AllowWithApproval, Deny, Prohibited, with no obligation dropped and no Prohibited effect overridden. It replies with an acknowledgement in the shape of ack-v1: accepted, or a conflict that lists every loosening rule with its rule id, the parent rule it loosens and the reason. Nothing is stored, no bundle changes and no event is published; a conflict for loosening counts in connectsoft.factory.policy.tightening_rejections. The model names asset-manifests-v1 as the request descriptor, which model/descriptors.yaml does not list, and this is reported. The publication gate of AgentRegistryService arrives in I4, so in this increment no service calls the method: it is hosted, and its contract and its comparison are proven by the suite, so that the complete registry binds to it without a change of the message. Both methods are called with a workload token that carries service scopes and no tenant claim, with the tenant and the project in the call metadata, read only under the service scope that names PolicyEngineService. A call without a workload identity is refused with UNAUTHENTICATED; a token without the service scope, and a user token, with PERMISSION_DENIED; a request without a tenant with INVALID_ARGUMENT; and a candidate document that cannot be read with INVALID_ARGUMENT, the position named and no document content in the log. When policy-engine-sql does not answer, both methods end UNAVAILABLE and the caller fails closed: RunControlService accepts no run and the registry publishes no policy release. The service retries nothing on its own.
Acceptance criteria
| AC1 | Given active bundles of the platform, of a tenant and of one of its projects, when PolicyEngineService/Policy.GetActiveRevision is called for the tenant with that project, with a project that has no bundle and for the tenant alone, then the replies name the project revision, the tenant revision and the tenant revision, each with its scope, its rulesHash and the revisions of its parents up to the platform bundle, and nothing is written; after a new tenant revision is activated the next call for the tenant names it, and it is the revision PolicyEngineService/PolicyRevisionActivated announced, while the call for the project with a bundle still names the project revision with the tenant revision it was validated against as its stored parent; for a tenant that has no tenant bundle yet the call seeds it once without an outbox record and names the seeded revision, and a later first decision of that tenant seeds nothing more (SCN-PolicyEngineService-007, ADR-0014). |
| AC2 | Given a tenant whose tenant revision was retired without a successor, a call without a workload identity, a workload token without the service scope or a user token, a request without a tenant, and policy-engine-sql stopped, when PolicyEngineService/Policy.GetActiveRevision or PolicyEngineService/Policy.ValidateTightening is called, then the answers are FAILED_PRECONDITION, for the first method and for a project candidate of that tenant sent to the second, whose parent scope has no active bundle, and UNAUTHENTICATED, PERMISSION_DENIED, INVALID_ARGUMENT and UNAVAILABLE for both, and no state changes (SCN-PolicyEngineService-007, SCN-PolicyEngineService-008, ADR-0015). |
| AC3 | Given a project candidate that only tightens the active tenant bundle, when PolicyEngineService/Policy.ValidateTightening is called, then the reply is accepted; given a candidate with a rule that is looser than its parent rule, that overrides a Prohibited effect or that drops an obligation, then the reply is a conflict that lists each loosening rule with its rule id, the parent rule and the reason, and connectsoft.factory.policy.tightening_rejections is incremented; in both cases no PolicyEngineService/PolicyBundle, rule row or outbox record is written (SCN-PolicyEngineService-008, model/services/governance/PolicyEngineService.yaml). |
| AC4 | Given a candidate document that cannot be read, when PolicyEngineService/Policy.ValidateTightening is called, then the answer is INVALID_ARGUMENT with the position named and the log holds no document content; given one candidate sent to this method and to the activation of AIFACTORY-US-916, then both give the same verdict, because one comparer serves both (SCN-PolicyEngineService-008, ADR-0021). |
| Traces: services | PolicyEngineService, RunControlService, AgentRegistryService |
| Traces: aggregates | PolicyEngineService/PolicyBundle |
| Traces: apis | PolicyEngineService/Policy.GetActiveRevision, PolicyEngineService/Policy.ValidateTightening |
| Traces: events | PolicyEngineService/PolicyRevisionActivated |
| Traces: descriptors | execution-scope-v1, ack-v1 |
| Traces: adrs | ADR-0014, ADR-0015, ADR-0021 |
| Traces: requirements | NFR-04, XL-02 |
| Traces: scenarios | SCN-PolicyEngineService-007, SCN-PolicyEngineService-008 |
| Depends on | AIFACTORY-US-916, feature:component-base-template-factory-profile |
| Sources | model/services/governance/PolicyEngineService.yaml, model/services/control-plane/RunControlService.yaml, model/descriptors.yaml, docs/architecture/adr/0014-run-and-lifecycle-envelopes.md, docs/planes/trust-operations/governance/services/policy-engine-service/index.md#apis |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-3703 Policy.GetActiveRevision for the scope of a new run |
implementation | Policy.GetActiveRevision reads the active revision of the narrowest scope of the request that has a bundle, the project bundle and else the tenant bundle, and returns it with its scope, rulesHash and the revisions of its stored parents up to the platform bundle in the reply message the proto fixes, also when a wider scope has activated a newer revision since; for a tenant without a tenant bundle, the platform tenant included, it runs the seed of AIFACTORY-TASK-3700 first and names the seeded revision, it answers FAILED_PRECONDITION for a tenant whose tenant revision was retired without a successor, writes nothing else, and maps the refusals UNAUTHENTICATED, PERMISSION_DENIED, INVALID_ARGUMENT and UNAVAILABLE; the proto is held with golden files. | ConnectSoft.AI.SoftwareFactory.PolicyEngineService |
AIFACTORY-TASK-3704 Policy.ValidateTightening on the tightening comparer of the activation |
implementation | Policy.ValidateTightening reads the candidate document of the request, resolves the active parent of its scope, answers FAILED_PRECONDITION and writes nothing when that parent scope has no active bundle, and otherwise runs the tightening comparer of AIFACTORY-TASK-3692; it replies accepted or a conflict that lists every loosening rule with its rule id, the parent rule and the reason, counts a conflict in connectsoft.factory.policy.tightening_rejections, answers INVALID_ARGUMENT with the position for an unreadable document, and stores, activates and publishes nothing; no document content is logged. | ConnectSoft.AI.SoftwareFactory.PolicyEngineService |
AIFACTORY-TASK-3705 Verify the active revision and the tightening check through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-PolicyEngineService-007\|Scenario=SCN-PolicyEngineService-008)"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-919 with the fixtures of AIFACTORY-TASK-3694 and AIFACTORY-TASK-3701: the revision named for a project with a bundle, a project without one and a tenant, the revision after a new activation, the stored parents of a project revision after a newer tenant revision, the seed of a tenant without a tenant bundle, the tenant whose revision was retired without a successor for both methods, every refusal, an accepted candidate, each kind of loosening candidate with its listed rules, an unreadable candidate, the equal verdict of the method and of the activation, and the stores and the outbox unchanged after every call. |
ConnectSoft.AI.SoftwareFactory.PolicyEngineService |
AIFACTORY-US-920: Read the active and the retired policy bundles and the rules of one revision¶
behavior · persona observer
As an observer, I want to read which policy bundles are in force for the platform, my tenant and my projects and what rules a revision holds, so that I can tell under which rules a run was decided without being able to change them.
A person reads which policy is in force. ListPolicyBundles, GET /factory/policies, returns the active and the retired bundles the caller may see, each with revision, scope, scope id, release, parent revision, domains, rulesHash, the active flag and activatedAt. GetPolicyBundle, GET /factory/policies/{revision}, returns the rules of one revision as the typed view of its document: rule id, domain, match, effect, obligations and priority. Both are of class read, need the scope factory.policies.read and write nothing. The callers are the roles the model names for the service, Reviewer, Operator, Workspace admin, Platform admin and Observer, and the Studio screen policies reads both. A user token has one audience, the gateway GovernanceHost, which forwards it unchanged, and the service accepts the audience of its own gateway and applies its own tenant filter and role rules (ADR-0015 amendment D117). A person reaches the two routes through the Governance gateway, which is delivered in I1 like the other gateways (D127); the feature builds no direct route. What a caller sees follows the scope hierarchy. Every caller with the scope sees the platform bundle and the tenant bundles of the tenant of the token. A project bundle is listed and served only to a caller who holds a role in that project or the tenant-wide Platform admin role, so a member of one project does not learn the rules of another. The platform bundle belongs to the platform tenant and is the one row of another tenant the tenant filter admits, read only. ListPolicyBundles is paged and may be filtered by scope and by the active flag. The model names no parameter for a project on it, so the call is served under the tenant of the token and filtered by the role claims, and the gap is reported as a correction of the service file. A call without a token or with an expired token is answered 401 and a token without factory.policies.read 403. GetPolicyBundle for a project bundle of a project in which the caller holds no role is answered 403. A revision that does not exist and a revision of another tenant are both answered 404, so the response never confirms that a foreign revision exists (ADR-0015 amendment D113). A workload token is refused with 403, because a REST operation names no service scope. A retired revision stays readable, because runs that pinned it finish on it and their decisions name it. When policy-engine-sql does not answer, the response is 503 with a problem response and nothing is served from a stale copy. The reads are counted and timed by the request telemetry of the Factory profile with tenant and project, and the rules of a bundle never reach a log record, an activity or a metric.
Acceptance criteria
| AC1 | Given active and retired bundles of the platform, of a tenant and of two of its projects and a caller with factory.policies.read and a role in one of the projects, when PolicyEngineService/ListPolicyBundles is called, then the response is 200 with the platform bundle, the tenant bundles and the bundles of that one project, each with revision, scope, scopeId, parentRevision, domains, rulesHash, active and activatedAt, paged; the filter by the active flag narrows the list; a Platform admin of the tenant is served every project bundle of the tenant; nothing is written (SCN-PolicyEngineService-001, FUX-01). |
| AC2 | Given a caller with factory.policies.read, when PolicyEngineService/GetPolicyBundle is called for an active and for a retired revision the caller may see, then each response is 200 with the typed rules of the revision, ruleId, domain, match, effect, obligations and priority, equal to the rule rows of that PolicyEngineService/PolicyBundle (SCN-PolicyEngineService-002). |
| AC3 | Given bundles of two tenants, when both operations are called with a token of one tenant, then no bundle of the other tenant is listed, the platform bundle is, and a revision of the other tenant is answered 404 exactly as an unknown revision is (SCN-PolicyEngineService-001, SCN-PolicyEngineService-002, ADR-0015, NFR-01). |
| AC4 | Given a call without a token or with an expired token, a token without the scope, a workload token, a project bundle of a project in which the caller holds no role, and policy-engine-sql stopped, when PolicyEngineService/ListPolicyBundles or PolicyEngineService/GetPolicyBundle is called, then the answers are 401, 403, 403, 403 and 503 with a problem response, no state changes and no rule content is found in the captured log records (SCN-PolicyEngineService-001, SCN-PolicyEngineService-002, ADR-0019). |
| Traces: services | PolicyEngineService |
| Traces: aggregates | PolicyEngineService/PolicyBundle |
| Traces: apis | PolicyEngineService/ListPolicyBundles, PolicyEngineService/GetPolicyBundle |
| Traces: adrs | ADR-0015, ADR-0019 |
| Traces: requirements | FR-01, FUX-01, NFR-01 |
| Traces: scenarios | SCN-PolicyEngineService-001, SCN-PolicyEngineService-002 |
| Relates: screens | policies |
| Depends on | AIFACTORY-US-916, feature:component-base-template-factory-profile |
| Sources | model/services/governance/PolicyEngineService.yaml, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/planes/trust-operations/governance/services/policy-engine-service/index.md#apis |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-3706 ListPolicyBundles and GetPolicyBundle with the visibility of project bundles |
implementation | ListPolicyBundles returns, paged and filterable by scope and by the active flag, the platform bundle, the tenant bundles of the tenant of the token and the project bundles of the projects in which the token holds a role, all project bundles of the tenant for the Platform admin; GetPolicyBundle returns the typed rules of one revision, active or retired; both answer 401, 403 and 404 as AIFACTORY-US-920 states, with 404 for an unknown revision and for a revision of another tenant alike, refuse a workload token with 403, answer 503 while the store does not answer, and log no rule content. | ConnectSoft.AI.SoftwareFactory.PolicyEngineService |
AIFACTORY-TASK-3707 Verify the reads of policy bundles through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-PolicyEngineService-001\|Scenario=SCN-PolicyEngineService-002)"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-920 over the token matrix and the two-tenant fixture of AIFACTORY-TASK-3701: the list for a member of one project and for a Platform admin, the paging and the filter, the typed rules of an active and of a retired revision, the 404 of a foreign and of an unknown revision, every refusal, the 503 while the store is stopped, and a scan of the captured log records for rule content. |
ConnectSoft.AI.SoftwareFactory.PolicyEngineService |
AIFACTORY-US-921: Validate a project override against the tenant bundle and simulate a candidate bundle against recorded decisions¶
behavior · persona workspace-admin
As a workspace admin, I want to check that the policy I plan for my project only tightens the policy of my tenant and to see which past decisions a candidate bundle would change, so that I never propose a policy that will be refused and I know its effect before it is in force.
Before a project policy is published it can be checked, and before a bundle changes, its effect on past work can be seen. Both operations are of class sandbox: they evaluate a candidate and store nothing, activate nothing and publish nothing. ValidateProjectPolicy, POST /factory/projects/{projectId}/policy/validate, takes a candidate project override in the typed shape of a bundle document and validates it against the active tenant bundle of the tenant of the token: every rule must tighten and none may loosen (D18). The scope is factory.policies.write, and the callers are the Workspace admin of the project and the Platform admin. The route names its project in the path. The gateway GovernanceHost of I1 (D127) admits it only for a token whose roles grant that project, and the service compares the path with the project roles of the forwarded token again and answers 403 for a project in which the caller is neither Workspace admin nor Platform admin of the tenant. The comparison is the one comparer of the activation and of Policy.ValidateTightening (AIFACTORY-US-916, AIFACTORY-US-919), so the three give one verdict for one document. The response is 200 with the result: valid, or not valid with every loosening rule listed with its rule id, the tenant rule it loosens and the reason; a not valid result counts in connectsoft.factory.policy.tightening_rejections. The model lists the codes 200, 400 and 403 and does not say which of them answers a loosening override. This PBI fixes 200 with a not valid result for a readable document that loosens, and 400 for a body that cannot be read as a bundle document, that names an unknown domain or effect or that names a scope other than the project of the path, and the reading is reported. The service holds no project registry. A Workspace admin is known from the role claim of the token for the project of the path. For a Platform admin, whose role is tenant-wide, the service asks Projects.ResolveScope of ProjectService for the tenant and the project of the path: a project that ProjectService answers as not existing in the tenant is answered 404 (ADR-0015 amendment D113), and when ProjectService does not answer the response is 503 and nothing is validated. A tenant that has no tenant bundle yet is seeded first, as at its first decision (AIFACTORY-US-918, D127). A tenant whose tenant revision was retired without a successor has nothing to validate against: the response is 409 with a problem response that names the missing tenant bundle, the REST form of the FAILED_PRECONDITION of AIFACTORY-US-919. When policy-engine-sql does not answer the response is 503. The code list of the model lacks 404 and 409, which is reported as a correction. A validated override is not in force: a project bundle becomes active only through the publication of a policy asset, which arrives with the complete registry in I4. SimulatePolicy, POST /factory/policies/simulate, answers what a candidate bundle would have decided. For a candidate document, its scope and a period, the service evaluates the recorded decisions of that scope and period that PolicyDecisions holds again under the candidate with its parents, and returns how many decisions were read, how many would change and, for each changed one, the decision id, the recorded effect, the simulated effect and the rules that matched. The inputs of a recorded decision are its stored subject, domain, action, action class and resource. No call to ProjectService or EnvironmentService is made, no decision is recorded, no cache entry is written and no event is published, and a simulated effect never leaves the response. The model calls the depth of this operation later-stage: this delivery simulates over the decisions of the hot window only, and simulation over the evidence copies of older decisions is a later capability the service page names. The model names no parameter for a project, so a candidate of project scope names its project in the body, and the service checks it against the roles of the token as above. A call without a token or with an expired token is answered 401; a token without factory.policies.write, a caller without the role and a workload token 403; an unreadable candidate or a period without a start or an end 400, a code the list of SimulatePolicy lacks and that is reported with the correction above; and a store that does not answer 503. Nothing changes state in any of these cases. A person reaches the two routes through the gateway GovernanceHost, delivered in I1 (D127).
Acceptance criteria
| AC1 | Given an active tenant bundle and a candidate project override every rule of which tightens it, when PolicyEngineService/ValidateProjectPolicy is called by the Workspace admin of the project of the path, then the response is 200 with the result valid, and no PolicyEngineService/PolicyBundle, rule row, decision, cache entry or outbox record was written (SCN-PolicyEngineService-003, model/services/governance/PolicyEngineService.yaml). |
| AC2 | Given a candidate override with a rule that is looser than the tenant rule, that overrides a Prohibited effect or that drops an obligation, when PolicyEngineService/ValidateProjectPolicy is called, then the response is 200 with the result not valid and every loosening rule listed with its rule id, the tenant rule it loosens and the reason, connectsoft.factory.policy.tightening_rejections is incremented, and the same document sent to Policy.ValidateTightening gives the same verdict (SCN-PolicyEngineService-003). |
| AC3 | Given a body that cannot be read as a bundle document, that names an unknown domain or effect or a scope other than the project of the path, a caller who is neither Workspace admin of the project nor Platform admin, a token without factory.policies.write, a call without a token, a Platform admin who names a project that ProjectService/Projects.ResolveScope answers as not existing in the tenant, a tenant whose tenant revision was retired without a successor, and policy-engine-sql stopped or, for the call of that Platform admin, ProjectService stopped, when PolicyEngineService/ValidateProjectPolicy is called, then the answers are 400, 403, 403, 401, 404, 409 and 503 with a problem response and no state changes (SCN-PolicyEngineService-003, ADR-0015). |
| AC4 | Given recorded decisions of a tenant and a candidate tenant document that turns one Allow rule into AllowWithApproval, when PolicyEngineService/SimulatePolicy is called for a period, then the response is 200 with the count of decisions read, the count that would change and, for each changed PolicyEngineService/PolicyDecision, its decision id, the recorded effect, the simulated effect and the matched rules; the tables, the cache and the outbox are unchanged and neither ProjectService nor EnvironmentService was called (SCN-PolicyEngineService-004). |
| AC5 | Given a call without a token, a token without the scope or a workload token, a candidate of project scope whose project the roles of the token do not grant, an unreadable candidate or a period without a start or an end, and policy-engine-sql stopped, when PolicyEngineService/SimulatePolicy is called, then the answers are 401, 403, 403, 400 and 503, no decision of another tenant was read and no state changes (SCN-PolicyEngineService-004, NFR-01). |
| Traces: services | PolicyEngineService, ProjectService |
| Traces: aggregates | PolicyEngineService/PolicyBundle, PolicyEngineService/PolicyDecision |
| Traces: apis | PolicyEngineService/ValidateProjectPolicy, PolicyEngineService/SimulatePolicy, ProjectService/Projects.ResolveScope |
| Traces: adrs | ADR-0015 |
| Traces: requirements | FR-01, NFR-01, NFR-04 |
| Traces: scenarios | SCN-PolicyEngineService-003, SCN-PolicyEngineService-004 |
| Relates: screens | policies |
| Depends on | AIFACTORY-US-916, AIFACTORY-US-918, AIFACTORY-US-919, feature:project-service |
| Sources | model/services/governance/PolicyEngineService.yaml, model/services/control-plane/ProjectService.yaml, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/planes/trust-operations/governance/services/policy-engine-service/index.md#later-capabilities |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-3708 ValidateProjectPolicy on the tightening comparer |
implementation | ValidateProjectPolicy reads the candidate override of the body, checks that its scope is the project of the path and that the caller is Workspace admin of that project or Platform admin of the tenant, runs the tightening comparer of AIFACTORY-TASK-3692 against the active tenant bundle and answers 200 with valid or with not valid and every loosening rule listed; it answers 400 for an unreadable document, an unknown domain or effect and a foreign scope, 403 and 401 as AIFACTORY-US-921 states, 404 for a project that a typed client of Projects.ResolveScope, asked for a Platform admin only, answers as not existing in the tenant, 409 with the missing tenant bundle named for a tenant without an active tenant bundle, and 503 while policy-engine-sql or, for the call of a Platform admin, ProjectService does not answer; it stores, activates and publishes nothing and counts a not valid result in connectsoft.factory.policy.tightening_rejections. | ConnectSoft.AI.SoftwareFactory.PolicyEngineService |
AIFACTORY-TASK-3709 SimulatePolicy over the recorded decisions of the hot window |
implementation | SimulatePolicy reads the recorded decisions of the scope and the period of the request from PolicyDecisions under the tenant filter, evaluates each again under the candidate document and its parents from the stored subject, domain, action, action class and resource without a call to ProjectService or EnvironmentService, and returns the count read, the count changed and each changed decision with its id, the recorded effect, the simulated effect and the matched rules; it checks the project of a project candidate against the roles of the token, answers 400 for an unreadable candidate and for a period without a start or an end, and writes no decision, no cache entry and no outbox record. | ConnectSoft.AI.SoftwareFactory.PolicyEngineService |
AIFACTORY-TASK-3710 Verify the validation of a project override and the simulation through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-PolicyEngineService-003\|Scenario=SCN-PolicyEngineService-004)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-921 with the documents of AIFACTORY-TASK-3694 and the fixtures of AIFACTORY-TASK-3701: a valid override, each kind of loosening override with its listed rules and the equal verdict of Policy.ValidateTightening, every refusal of both operations, among them the 404 the fake of Projects.ResolveScope gives for a Platform admin, the 409 of the tenant without a tenant bundle and the 503 while the store or ProjectService is stopped, a simulation that names the changed decisions, a simulation over two tenants that reads one, and a comparison of the tables, the cache and the outbox before and after every call. |
ConnectSoft.AI.SoftwareFactory.PolicyEngineService |
AIFACTORY-US-922: Read the policy decisions of a run and move decisions past the hot window to the immutable store¶
behavior · persona reviewer
As a reviewer, I want to read every policy decision of a run of my project with its effect, its rules and its reasons, so that I understand why an action of the run was allowed, gated or denied, and the decision is still evidence years later.
Every decision of a run can be read, and a decision is kept as evidence long after its run. ListRunDecisions, GET /factory/runs/{runId}/policy-decisions, returns the decisions recorded for a run in the order they were evaluated, each with decision id, domain, action, action class, effect, policy revision, obligations, matched rules, reasons and evaluatedAt. It is of class read, needs the scope factory.runs.read and writes nothing. The Studio screens run-detail and policies read it, and the callers are the roles the model lists for the service: Reviewer, Operator, Workspace admin and Observer of the project of the run and the Platform admin. The role Requester is not among them, so a member who holds only that role cannot read the decisions of a run that member requested; whether the role belongs in the service file is reported to the owner. The route names a run and no project. The service holds no run registry, only the tenant, the project and the run id each decision carries, so it answers from its own rows: a caller without a role in the project of the decisions is refused with 403, and a run id for which the tenant of the token holds no decision is answered 404, whether the run belongs to another tenant, does not exist or has no decision yet, so the response never confirms a foreign run (ADR-0015 amendment D113). A call without a token or with an expired token is answered 401, a token without factory.runs.read 403, a workload token 403, and a store that does not answer 503. The response holds what a decision holds, identifiers, classes, rule ids, reasons and hashes, and never prompt text, a secret or a payload, because a decision never contains them. A person reaches the route through the gateway GovernanceHost, delivered in I1 (D127). A decision is immutable: no operation of the service updates one, and a test fails when the mapping of PolicyDecisions allows an update. The worker DecisionRetentionSweeper keeps the table small without losing evidence. It runs on the schedule 0 2 * * * of the model and takes the decisions older than the hot window of 90 days the model states, partitioned by tenant with at most two partitions in parallel. It writes each decision as an evidence copy to the immutable audit store, the store binding audit-immutable the model lists for this service, where it is kept seven years (D31), and removes the row from PolicyDecisions only after the copy is confirmed. It is idempotent on the decision id: a decision whose copy exists is not written twice, a run that is interrupted between the copy and the removal removes the row on the next run, and a duplicate trigger has no second effect. A failed batch is retried by the fixed policy of the model, three attempts with a backoff of 300 seconds. When the attempts are used up the rows stay in the table, the failure is logged with the tenant and the count and without decision content, and the next scheduled run takes them again, so nothing is lost. The worker publishes no event. After the move ListRunDecisions no longer lists the decision, because it reads PolicyDecisions. The model does not say whether the read must also serve moved decisions, and the store audit-immutable is owned by AuditService while this service binds it; both points are reported to the owner. AuditService holds its own evidence of every decision from PolicyDecisionRecorded.
Acceptance criteria
| AC1 | Given decisions of one run under two revisions and a caller with factory.runs.read and a role in the project of the run, when PolicyEngineService/ListRunDecisions is called, then the response is 200 with the decisions in the order of their evaluation, each PolicyEngineService/PolicyDecision with decision id, domain, action, action class, effect, policy revision, obligations, matched rules, reasons and evaluatedAt, and nothing is written (SCN-PolicyEngineService-005, NFR-04). |
| AC2 | Given a call without a token, a token without factory.runs.read or a workload token, a caller without a role in the project of the decisions, a run id for which the tenant of the token holds no decision, which includes a run of another tenant, and policy-engine-sql stopped, when PolicyEngineService/ListRunDecisions is called, then the answers are 401, 403, 403, 404 and 503 with a problem response and no state changes (SCN-PolicyEngineService-005, ADR-0015). |
| AC3 | Given decisions older and younger than the hot window of model/services/governance/PolicyEngineService.yaml in two tenants, when DecisionRetentionSweeper runs, then each older decision exists as an evidence copy in the immutable store and no longer in PolicyDecisions, the younger ones are untouched, at most two tenant partitions ran in parallel, and a second run and a duplicate trigger write no second copy and publish nothing. |
| AC4 | Given the immutable store refuses writes, when the worker runs, then after three attempts with the backoff of the model the rows are still in PolicyDecisions, the failure is logged with the tenant and the count and without decision content, and the next run moves them; given a run interrupted between the copy and the removal, then the next run removes the row without a second copy, so no PolicyEngineService/PolicyDecision is lost or duplicated (ADR-0019, NFR-10). |
| Traces: services | PolicyEngineService, AuditService |
| Traces: aggregates | PolicyEngineService/PolicyDecision |
| Traces: apis | PolicyEngineService/ListRunDecisions |
| Traces: adrs | ADR-0015, ADR-0019 |
| Traces: requirements | NFR-04, NFR-10 |
| Traces: scenarios | SCN-PolicyEngineService-005 |
| Relates: screens | run-detail, policies |
| Depends on | AIFACTORY-US-918, feature:component-base-template-factory-profile |
| Sources | model/services/governance/PolicyEngineService.yaml, model/stores.yaml, docs/architecture/adr/0019-data-governance.md, docs/planes/trust-operations/governance/services/policy-engine-service/index.md#workers-and-jobs |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-3711 ListRunDecisions from the decision rows of the tenant |
implementation | ListRunDecisions returns the decisions of a run id under the tenant filter in the order of evaluatedAt with decision id, domain, action, action class, effect, policy revision, obligations, matched rules and reasons; it answers 403 for a caller without a role in the project the decisions carry, 404 for a run id without a decision in the tenant of the token, 401, 403 for a token without factory.runs.read and for a workload token, and 503 while the store does not answer; it writes nothing. | ConnectSoft.AI.SoftwareFactory.PolicyEngineService |
AIFACTORY-TASK-106 Worker: DecisionRetentionSweeper |
implementation | The worker runs on the schedule 0 2 * * * with the fixed retry policy of the model, three attempts with a backoff of 300 seconds, partitioned by TenantId with at most two partitions in parallel and idempotent on decisionId; it writes each decision older than the hot window of 90 days as an evidence copy to the store binding audit-immutable, removes the row from PolicyDecisions only after the copy is confirmed, leaves the rows in place when the attempts are used up, logs the tenant and the count without decision content, and publishes no event; a duplicate trigger has no second effect. | ConnectSoft.AI.SoftwareFactory.PolicyEngineService |
AIFACTORY-TASK-3712 Verify the decisions of a run and the retention sweep through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-PolicyEngineService-005" and dotnet test -c Release --filter "Category=Acceptance&Feature=DecisionRetention"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-922: the ordered decisions of a run, every refusal over the token matrix and the two-tenant fixture of AIFACTORY-TASK-3701, the move of old decisions with the clock of the suite and a blob store double, the repeated and the duplicate run, the refused write with its three attempts, and the interrupted run. |
ConnectSoft.AI.SoftwareFactory.PolicyEngineService |