AIFACTORY-FEAT-164: SaaS Metering template: idempotent usage, windows and the quota contract before usage export¶
Generated from the architecture model
This page is rendered from model/**/*.yaml by tools/docs_model during mkdocs build. Edit the YAML, not this page; hand-written design lives on the linked service, platform and plane pages.
A design artefact, not a tracker
This backlog is generated from model/backlog/ and validated against the architecture model. No work item exists in any tracker, and no item carries a date, an estimate or an assignee (ADR-0029).
Epic Ecosystem component extensions · Increment I4 Trust and accountability · State elaborated · Route backend-developer · Phase before development · Build order 34 of 185 (Templates and libraries)
Before development
Template or library work: every task of this feature changes a template or a shared library the Factory builds on, and it lands before the Factory's own repositories of I4 are developed. The mark travels with every task (tag phase:before-development).
CostUsageService exports usage to the SaaS Metering service and the export must be repeatable without a duplicate meter (FEAT-102); budgets are capped per period and invoices read the same measurement. The template's own gap backlog (saas-EPIC-MET) is not started: a usage record has no idempotency key, counters are flat with a boolean reset instead of windows, the quota events name Dimension where Billing expects MeterKey, and the inbound usage topic is not registered. FEAT-102 depends on this feature. Component: SaaS Metering service (extend).
| Delivers | — |
| Stubs | — |
| Realizes | components: cmp-saas-metering adrs: ADR-0014, ADR-0020 bounded contexts: BC-34 |
| Requirements | — |
| Depends on | — |
| Sources | model/components.yaml, ConnectSoft.Saas.MeteringTemplate/Docs/backlog/metering-gap-backlog.md |
AIFACTORY-US-279: SaaS Metering template: a usage record carries an idempotency key, and a repeated record changes no counter and returns the first result¶
enabling · persona asset-maintainer
As an asset maintainer, I want usage ingestion of a generated Metering service to be idempotent on a key the caller supplies, so that an exporter can repeat a delivery without inflating a counter.
Feature saas-MET-F01 of the gap backlog of the template (Docs/backlog/metering-gap-backlog.md of the template) records that usage ingestion is not idempotent. RecordUsageInput and RecordUsageRequest carry a tenant, a dimension and a delta; DefaultUsageMetersProcessor.RecordUsageAsync always increments the counter, raises the aggregate version and publishes the usage-recorded event; the descriptor ConnectSoft.Saas.Metering.json lists no value object. The published language of the SaaS family requires deduplication on tenant, dimension and idempotency key under at-least-once delivery. The Factory exports its usage to this service and must be able to repeat an export, and CostUsageService creates a usage record from a receipt exactly once (model/services/control-plane/CostUsageService.yaml). This PBI adds the value object UsageRecord with the time of occurrence, the quantity, the source and the idempotency key, puts the key on the REST and gRPC record operations, where it is required, and has the processor count a usage once per tenant, dimension and key. A repeated record with the same key and the same quantity changes no counter, publishes no second event and returns the result of the first. A record with the same key and a different quantity is refused as a conflict and changes nothing, the rule ADR-0014 decision 3 states for idempotency. A record without a key is refused as invalid. The saga path that records usage from an inbound message derives the key from the identifier of that message. The deduplication row, the counter change and the outbox record of the event are committed in one transaction of the store of the service, so a rollback leaves none of them. The descriptor lists the value object, because the descriptor is the import format of ADR-0025 and must describe the code. The script build/regenerate.ps1 cannot prove that it does: without a Factory endpoint it only parses the descriptor as JSON and reads neither the code nor a schema. This PBI therefore adds a descriptor drift test, as AIFACTORY-TASK-1143 did for the Tenants template: an architecture test that compares ConnectSoft.Saas.Metering.json in both directions with the usage meter entity, the value objects and the published and consumed event types, validates it against ConnectSoft.Saas.Metering.schema.json and names the member on a difference. The later PBIs of the feature and its gate use this test as the validator of the descriptor.
Acceptance criteria
| AC1 | Given a usage record with an idempotency key, when the same record is delivered three times over REST and over gRPC, then the counter grows once, one usage-recorded event is published and all three calls return the result of the first (ADR-0014 decision 3, ADR-0020 decision 3). |
| AC2 | Given a recorded key, when a record with the same key and a different quantity arrives, then it is refused as a conflict with 409 and no counter or event changes; given a record without a key, then it is refused with 400; given two records with different keys on one dimension, then both are counted (ADR-0014 decision 3). |
| AC3 | Given a record whose transaction rolls back after the counter change, when the store is read, then no deduplication row, no counter change and no outbox record exists, and a later delivery of the same key is counted once (ADR-0014 decision 4, model/services/control-plane/CostUsageService.yaml). |
| AC4 | Given the descriptor ConnectSoft.Saas.Metering.json, when the descriptor drift test runs, then the descriptor validates against ConnectSoft.Saas.Metering.schema.json, lists the value object UsageRecord with its fields, and equals the usage meter entity, the value objects and the published and consumed event types of the code in both directions; a planted extra property, which is valid JSON and passes the parse of build/regenerate.ps1, fails the test with the member named (ADR-0025 decision 2). |
| Traces: services | CostUsageService |
| Traces: adrs | ADR-0014, ADR-0020, ADR-0025 |
| Sources | model/components.yaml, model/services/control-plane/CostUsageService.yaml, model/template-parameters/connectsoft-saas-metering.yaml, docs/architecture/adr/0020-commercial-model.md, docs/architecture/adr/0014-run-and-lifecycle-envelopes.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1255 Value object UsageRecord, the key on the record contracts and the descriptor entry |
contract | The entity model declares the value object UsageRecord with time of occurrence, quantity, source and idempotency key; RecordUsageInput, RecordUsageRequest and the gRPC contract carry the key as a required field with the 400 and 409 answers documented on the REST and gRPC pages; the descriptor ConnectSoft.Saas.Metering.json lists the value object. |
ConnectSoft.Saas.MeteringTemplate |
AIFACTORY-TASK-1292 Descriptor drift test over the usage meter entity, the value objects and the event types |
fixture | An architecture test reads ConnectSoft.Saas.Metering.json, validates it against ConnectSoft.Saas.Metering.schema.json and compares it in both directions with the usage meter entity, the value objects and the published and consumed event types of the messaging model; a difference fails the test with the member named, and a planted extra property proves it; build/regenerate.ps1 stays the parse of the descriptor it is. |
ConnectSoft.Saas.MeteringTemplate |
AIFACTORY-TASK-605 Usage record with an idempotency key (saas-MET-F01) |
implementation | RecordUsage carries a usage record with a caller-supplied idempotency key; DefaultUsageMetersProcessor.RecordUsageAsync counts once per tenant, dimension and key, a repeated record with the same key changes no counter and returns the first result, the same key with another quantity is a conflict, and the saga path derives the key from the message identifier; a test delivers the same record three times. |
ConnectSoft.Saas.MeteringTemplate |
AIFACTORY-TASK-1256 Deduplication table with its unique index and mapping |
migration | A migration adds the usage record table with a unique index on tenant, dimension and idempotency key and its mapping; the row is written in the transaction of the counter change and the outbox record; mapping tests run against an isolated test database and include the rollback case. | ConnectSoft.Saas.MeteringTemplate |
AIFACTORY-TASK-1257 Verify the idempotent record over REST and gRPC |
verification | Run dotnet test -c Release --no-build on the template solution; the triple delivery, conflict, missing key and rollback tests over both transports and the descriptor drift test with its planted property pass and prove AC1 to AC4 of AIFACTORY-US-279 (ADR-0014, ADR-0020). |
ConnectSoft.Saas.MeteringTemplate |
AIFACTORY-US-280: SaaS Metering template: a counter belongs to a window, a roll or the passed boundary of a Fixed window closes it and opens the next, and threshold and quota events carry the window¶
enabling · persona asset-maintainer
As an asset maintainer, I want usage counted per window that follows the subscription period, so that a budget is capped per period and an invoice reads the usage of exactly its period.
Feature saas-MET-F02 of the gap backlog of the template records that a meter is one scalar CounterValue per tenant and dimension, that a window is only approximated by the flags ThresholdCrossedEmitted and QuotaExceededEmitted, which RollUsageCounterInnerAsync resets on a roll, that a roll is manual or driven by an API call and not tied to a period boundary, and that the events carry no window identifier. ADR-0020 has budgets capped per period and invoices read the same measurement, so the Factory needs to say which period a usage was counted in. This PBI adds the value object Window with its kind, fixed or rolling, its size, its anchor and a window identifier, and makes the counter belong to the open window of its meter. Within an open window the counter never decreases. A roll closes the open window, keeps its total and opens the next window with a counter of zero; the counter-rolled event and the threshold and quota events carry the window identifier, and the two flags are kept per window, so a threshold is announced once per window. A window does not wait for a caller. A Fixed window whose anchor plus size has passed is closed and the next one opened by the service itself, by a scheduled job of the scheduler model of the template and, at the latest, by the next record that arrives after the boundary, with one counter-rolled event and no API call; two instances that reach the boundary together roll once. Without this no window of a tenant would close before Billing publishes a rating-window event, and a reconciliation would have nothing to compare. A usage record is counted in the window that is open when it is recorded, and its result names that window, the start of that window and the time of occurrence of the record, so that a caller can tell a record whose time of occurrence precedes the window it was counted in. The rating-window event of Billing, which the backlog names as an optional trigger and marks as the dependency saas-BIL-F07 of the Billing template, opens the window an invoice period needs; a second delivery of the same event opens nothing. The Billing template does not publish that event in this increment, so the Metering template declares the inbound contract itself until the Billing template publishes against it, with a golden file, a topic constant, its registration in MeteringMassTransitTopology and its entry among the consumed events of the descriptor, the very omission saas-MET-F03 records for the usage-reported event, and its test publishes the message. A roll of a window that is already closed is refused as a conflict. The existing counter of a meter becomes its first open window when the migration runs. The descriptor lists the value object.
Acceptance criteria
| AC1 | Given a meter with usage in its open window, when the window is rolled, then the window is closed with its total kept, a new window with a counter of zero is open, and the counter-rolled event carries the identifiers of both windows; a roll of a closed window is refused with 409 (ADR-0020 decision 3, model/components.yaml). |
| AC2 | Given a quota and a threshold on a meter, when usage crosses them in one window and again in the next, then the threshold and quota events are published once per window and each carries its window identifier; the result of a usage record names the window it was counted in, the start of that window and the time of occurrence of the record (ADR-0020 decision 3). |
| AC3 | Given the inbound rating-window contract the Metering template declares itself, with its golden file, its topic constant, its registration in MeteringMassTransitTopology and its entry among the consumed events of the descriptor, when a test publishes a rating-window message for a subscription period, because saas-BIL-F07 of the Billing template is not delivered in this increment, then the window of that period is opened for the meters of the tenant, and a second delivery of the same message opens no further window (ADR-0014 decision 3, ADR-0020 decision 2). |
| AC4 | Given a store with flat counters of the template before this PBI, when the migration runs, then each counter is the total of the first open window of its meter and no usage is lost; the descriptor lists the value object Window and the inbound rating-window event, and the descriptor drift test passes (ADR-0025 decision 2). |
| AC5 | Given a meter with a Fixed window whose anchor plus size has passed and no caller that rolls it, when the scheduled job of the service runs or the next usage record arrives, then the window is closed with its total kept, the next window is open, exactly one counter-rolled event is published although two instances reach the boundary together, and the arriving record is counted in the new window (ADR-0020 decision 3, model/components.yaml). |
| Traces: services | CostUsageService |
| Traces: adrs | ADR-0014, ADR-0020, ADR-0025 |
| Depends on | AIFACTORY-US-279 |
| Sources | model/components.yaml, model/template-parameters/connectsoft-saas-metering.yaml, docs/architecture/adr/0020-commercial-model.md, docs/architecture/commercial-model.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1258 Value object Window, the window identifier on the events, the inbound rating-window contract and the descriptor entries |
contract | The entity model declares the value object Window with kind, size, anchor and window identifier; the counter-rolled, threshold and quota events and the usage record carry the window identifier as an added field of their current version, and the result of a record names the window and its start; the messaging model declares the inbound rating-window contract with a topic constant and a golden JSON file; the descriptor lists the value object and the inbound event among its consumed events, and the events page of the template names the field and the inbound topic. |
ConnectSoft.Saas.MeteringTemplate |
AIFACTORY-TASK-606 Window semantics aligned with the subscription period (saas-MET-F02) |
implementation | A counter belongs to a window; a roll closes the window and opens the next; threshold and quota events carry the window id and their flags are kept per window; MeteringMassTransitTopology registers the inbound rating-window contract, and its consumer opens the window the invoice period needs and is idempotent; RollUsageCounterInnerAsync and PrepareQuotaTransitions work on the open window and no longer on bare flags. |
ConnectSoft.Saas.MeteringTemplate |
AIFACTORY-TASK-1297 Fixed window closed at its boundary by the service itself |
implementation | A scheduled job of the scheduler model of the template closes every Fixed window whose anchor plus size has passed and opens the next, and the record path does the same before it counts a record that arrives after the boundary; the roll is guarded so that two instances roll a window once and publish one counter-rolled event; no API call and no event of Billing is needed. | ConnectSoft.Saas.MeteringTemplate |
AIFACTORY-TASK-1259 Window columns on the meter store and the migration of flat counters |
migration | A migration adds the window table and the window reference of the usage record and turns the existing counter of every meter into the total of its first open window; a migration test runs on a store seeded with flat counters and compares the totals before and after. | ConnectSoft.Saas.MeteringTemplate |
AIFACTORY-TASK-1260 Verify the roll, the per-window events and the migration |
verification | Run dotnet test -c Release --no-build on the template solution; the roll invariants, the boundary close by the job and by the next record with two instances, the per-window threshold and quota events, the rating-window consumer with its golden file and its duplicate delivery, the descriptor drift test and the migration test pass and prove AC1 to AC5 of AIFACTORY-US-280 (ADR-0020). |
ConnectSoft.Saas.MeteringTemplate |
AIFACTORY-US-288: SaaS Metering template: a tenant scoped, paged query returns the usage records of one tenant, dimension and window and the total of a closed window, over REST and gRPC¶
enabling · persona asset-maintainer
As an asset maintainer, I want a generated Metering service to return the usage records and the total of one window, so that a caller can compare what it recorded with what the service counted, record by record.
The usage meters controller of the template offers two reads, queries/by-tenant-dimension and queries/by-id, and each returns one meter with its counter (UsageMeterDto.CounterValue). With the usage record and the window of the earlier PBIs the service stores which record was counted in which window, but no operation returns them. The meter reconciliation of the feature component-saas-metering (AIFACTORY-US-286) compares the settled usage of the Factory with the usage records and the total of one window of the Metering service, and AIFACTORY-US-287 proves it against a generated service without a stub, so the generated service must offer that read. This PBI adds it. The requests, the responses and the operations on the two service interfaces are declared in ConnectSoft.Saas.Metering.ServiceModel, the package the REST page of the template names as the home of the contracts, and the REST controller and the code first gRPC service implement them. The query takes a dimension and a window identifier; the tenant is the tenant context of the call and never a free field of the request. It returns the window with its kind, start, end and state, the total of the window, which is final once the window is closed and marked as running while it is open, and one page of usage records, each with its idempotency key, quantity, time of occurrence, source and window identifier, in a stable order by time of occurrence and key with a continuation token. A second operation lists the windows of a tenant and dimension that closed after a given window, so that a caller finds what it has not compared yet. A window identifier of another tenant is answered 404, the same answer as for an identifier that does not exist, an unknown dimension is answered 404, and a page size above the limit of the options is refused with 400. The query only reads and changes no counter, and it adds nothing to the descriptor, so the descriptor drift test stays as it is.
Acceptance criteria
| AC1 | Given a tenant with usage records in a closed window of one dimension, when the query is called over REST and over gRPC with the dimension and the window identifier, then both return the window with its start, end and state, its final total, and the usage records with idempotency key, quantity, time of occurrence, source and window identifier, and the sum of the quantities over all pages equals the total (ADR-0020 decision 3, model/components.yaml). |
| AC2 | Given more records than one page holds, when the caller follows the continuation token, then every record of the window is returned exactly once in a stable order although new usage is recorded in the open window meanwhile, and a page size above the limit of the options is refused with 400 (ADR-0020 decision 3, docs/architecture/commercial-model.md). |
| AC3 | Given a window identifier of another tenant, when the query is called, then the answer is 404 with the same body as for an identifier that does not exist, and over gRPC the status NOT_FOUND; the tenant of the query is the tenant context of the call and no field of the request (ADR-0015 amendment on a resource of another tenant). |
| AC4 | Given windows of a tenant and dimension that closed after a given window, when the list of closed windows is read, then it returns each with its identifier, start, end and total in the order they closed, and the record query of an open window returns its total marked as running, so that the reconciliation of model/services/control-plane/CostUsageService.yaml compares closed windows only (ADR-0020 decision 3). |
| Traces: services | CostUsageService |
| Traces: adrs | ADR-0015, ADR-0020 |
| Depends on | AIFACTORY-US-279, AIFACTORY-US-280 |
| Sources | model/components.yaml, model/services/control-plane/CostUsageService.yaml, docs/architecture/adr/0020-commercial-model.md, docs/architecture/commercial-model.md, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1293 Requests, responses and operations of the window query in the ServiceModel package |
contract | ConnectSoft.Saas.Metering.ServiceModel declares the request and the paged response of the usage records of a window (the window with kind, start, end and state, the total with its running mark, the records with idempotency key, quantity, time of occurrence, source and window identifier, and the continuation token), the request and the response of the list of closed windows, and both operations on the REST and the code first gRPC service interfaces, with the 400 and 404 answers documented on the REST and gRPC pages of the template. |
ConnectSoft.Saas.MeteringTemplate |
AIFACTORY-TASK-1294 Window query in the REST controller and the gRPC service over a tenant filtered, paged read |
implementation | The usage meters controller and the gRPC service implement the two operations over a read of the usage record and window tables that is filtered by the tenant context, ordered by time of occurrence and key, paged by a continuation token and bounded by the page size limit of the options; a window of another tenant, an unknown identifier and an unknown dimension are answered 404, and nothing is written. | ConnectSoft.Saas.MeteringTemplate |
AIFACTORY-TASK-1295 Query tests over both transports with paging, a foreign tenant and an open window |
fixture | Acceptance tests of the template seed two tenants with closed and open windows and call both operations over REST and gRPC: the sum of the pages equals the total, paging returns every record once while usage is recorded, a window of the other tenant is answered 404, a page size above the limit is refused with 400, the total of an open window is marked as running, and the list of closed windows is in closing order. | ConnectSoft.Saas.MeteringTemplate |
AIFACTORY-TASK-1296 Verify the window query over REST and gRPC |
verification | Run dotnet test -c Release --no-build on the template solution; the query tests over both transports pass and prove AC1 to AC4 of AIFACTORY-US-288 (ADR-0020, ADR-0015). |
ConnectSoft.Saas.MeteringTemplate |
AIFACTORY-US-281: SaaS Metering template: the quota events carry the meter key Billing reads, and the inbound usage-reported topic is registered so that reported usage reaches the quota saga¶
enabling · persona asset-maintainer
As an asset maintainer, I want the two contracts that connect Metering to its neighbours to hold from end to end, so that reported usage is counted and a quota that is exceeded is understood by the service that acts on it.
Two features of the gap backlog of the template carry its highest priority because they block the path from end to end. Feature saas-MET-F03 records that the inbound event UsageReportedForQuotaInboundEvent and the saga UsageMeterQuotaEnforcementStateMachine exist, and that the saga calls the record operation, but that MeteringMassTransitTopology registers three other inbound events and not this one, and that no topic constant exists, so a publisher has nothing to bind to. Feature saas-MET-F04 records that QuotaExceededIntegrationEvent and QuotaThresholdCrossedIntegrationEvent publish a property named Dimension, while the inbound contract of Billing expects MeterKey; the topic names already agree. The cross-cutting slice saas-INTEG-F02 of the same backlog names MeterKey as the name on the Metering events. This PBI closes both. The two quota events carry MeterKey; Dimension stays as a deprecated alias with the same value in the current version of the events, an additive change under the versioning rule of the events page of the template, so no second topic is needed. Golden files fix the serialised form of both events, and a contract test reads them back through the field Billing expects; the golden files are the fixture the Billing template consumes in its own inbound test. The inbound usage-reported topic gets its constant, its registration in the topology and its entry among the consumed events of the descriptor, with the canonical topic name of the published language. A test publishes a usage-reported message and finds the usage recorded once through the saga, with the idempotency key derived from the message identifier, and a second delivery of the message counted nowhere. The MassTransit topology is the transport of generated products and stays; what the Factory profile publishes is the next PBI.
Acceptance criteria
| AC1 | Given a quota that is exceeded and a threshold that is crossed, when the two quota events are serialised, then each carries MeterKey and the alias Dimension with the same value, each matches its golden file, and the contract test reads the meter identity through the field Billing expects (ADR-0020 decision 2, model/components.yaml). |
| AC2 | Given the topology and the descriptor of the template, when they are inspected, then the usage-reported inbound topic has a constant, a registration and an entry among the consumed events of the descriptor, and the descriptor drift test passes (ADR-0025 decision 2, ADR-0012). |
| AC3 | Given a publisher that sends a usage-reported message to the registered topic, when the saga consumes it, then the usage is recorded once with the key derived from the message identifier and the quota is evaluated; a second delivery of the same message changes no counter (ADR-0014 decision 3). |
| Traces: adrs | ADR-0012, ADR-0014, ADR-0020, ADR-0025 |
| Depends on | AIFACTORY-US-279 |
| Sources | model/components.yaml, model/template-parameters/connectsoft-saas-metering.yaml, docs/architecture/adr/0020-commercial-model.md, docs/architecture/adr/0012-messaging-port-and-transport-profiles.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-607 Quota contract aligned with Billing and the inbound usage topology (saas-MET-F03, saas-MET-F04) |
contract | The quota events carry MeterKey, the field Billing deserializes, with Dimension kept as a deprecated alias, proven by golden files and a contract test that reads them through the field Billing expects; the UsageReportedForQuota inbound topic has its constant, and the events page of the template names the canonical field and the topic. |
ConnectSoft.Saas.MeteringTemplate |
AIFACTORY-TASK-1261 Inbound usage-reported topic registered in the topology and the descriptor |
implementation | MeteringMassTransitTopology registers the entity name of UsageReportedForQuotaInboundEvent under the topic constant, the descriptor lists the event among its consumed events, PrepareQuotaTransitions fills MeterKey, and the saga passes the key derived from the message identifier to the record operation. |
ConnectSoft.Saas.MeteringTemplate |
AIFACTORY-TASK-1262 Golden files of the quota events and the saga test of reported usage |
fixture | Golden JSON files of the two quota events are kept with the tests and published as a test artifact of the template pipeline for the Billing template to consume; a saga test publishes a usage-reported message twice and asserts one recorded usage and one quota evaluation. | ConnectSoft.Saas.MeteringTemplate |
AIFACTORY-TASK-1263 Verify the quota contract and the inbound usage path |
verification | Run dotnet test -c Release --no-build on the template solution; the golden file tests, the contract test of the meter key, the descriptor drift test and the saga test pass and prove AC1 to AC3 of AIFACTORY-US-281 (ADR-0020, ADR-0025). |
ConnectSoft.Saas.MeteringTemplate |
AIFACTORY-US-282: SaaS Metering template: under UseFactoryProfile the events keep the complete envelope base that a Factory consumer maps, leave through the Orleans outbox, and only allowed dimensions are counted¶
enabling · persona asset-maintainer
As an asset maintainer, I want the Metering service of the Factory to publish its events in the envelope and on the profile every Factory service uses, so that the usage reconciliation of the Factory correlates a meter event by tenant and run without a second envelope.
The events page of the template (Docs/events.md of the template) names the common envelope of the metering events, tenant, aggregate identifier, aggregate version, schema version, correlation identifier and causation identifier, four topics, and delivery through the built-in outbox of MassTransit. The envelope has no time of occurrence, which the run event envelope requires, and no run. The amendment of ADR-0014 on envelopes per event family keeps a generic SaaS template on its own envelope base and has the Factory profile map it. That mapping is applied on receipt, in the inbox of the consuming Factory service, by the scope chain of the base template profile (AIFACTORY-US-227), as AIFACTORY-US-251 of the Tenants template records for its events. No outbound mapping exists in any PBI, so the Metering service does not write the run event envelope. The amendment of ADR-0028 on the Factory profile switch selects the Factory shape by the boolean parameter UseFactoryProfile, off by default. This PBI brings the parameter into the template as the symbol the base template defines, received through the base-template submodule: the submodule pointer moves to the base template that carries the symbol and the Orleans value of MessagingModelType, the template metadata is reconciled and build/MaterializedDirectory.Packages.props is regenerated. The envelope base of the four outbound events is completed with occurredOn, in every generation, as an added field of the current version. The usage record gains an optional run identifier beside its source, and the body of the usage-recorded event carries it when the record names one. With the parameter on, the four events keep that envelope base on the wire and are dispatched through the outbox of the Orleans messaging profile, committed with the counter change. The events page records the mapping table onto the run event envelope that the consuming service applies: tenantId, schemaVersion, correlationId and causationId map by name, occurredOn is occurredAt, the message identifier of the publication is eventId, the topic name is eventType, the messaging service name of the Metering service is producer, the event body is payload, the run identifier of the usage-recorded body is runId, and aggregateId with aggregateVersion gives the ordering key. The template adds no envelope type and no messaging code. The REST page of the template states that every endpoint requires a tid claim, and a workload token carries a service scope and no tenant claim. Under the profile the tenant a caller forwards is admitted into the tenant context the endpoints require when its workload token holds the service scope that names the Metering service; without that scope the call is refused with 403, and a usage meter of another tenant is answered 404. The profile also binds an allowed dimension option. The template takes a free string dimension per tenant today (EnsureUsageMeterProvisionedRequest), has no registry of dimensions and no unit, and counts in 64 bit integers (UsageMeterDto.CounterValue, RecordUsageRequest.Delta). Under the profile the option lists the allowed dimensions, each with its key and its unit, the smallest whole unit the integer counter counts in. It is bound and validated at start, a meter is provisioned and a usage is recorded only for a listed key, and another key is refused with 400; an empty list refuses the start. Without the profile the dimension stays the free string a product takes from its Products Catalog. With the parameter off, the template generates what it generates today: its own envelope on the MassTransit topology with the same topics, completed with occurredOn.
Acceptance criteria
| AC1 | Given a Metering service generated with UseFactoryProfile, when a usage is recorded, a counter is rolled and a quota is crossed and exceeded, then each of the four events is serialised in the envelope base of the template, complete with occurredOn, the usage-recorded body carries the run identifier when the usage record names one, each event matches its golden file, and the mapping table of the events page names a source for every required field of run-event-envelope-v1 (ADR-0014 decision 1 and its amendment on envelopes per event family, docs/reference/schemas/run-event-envelope.schema.json). |
| AC2 | Given the same service, when the unit of work of a record commits, then the outbox record of the event is committed with the counter change and dispatched through the Orleans messaging profile, and when it rolls back no record and no event exists; a consumer on the Orleans inbox that applies the mapping of AIFACTORY-US-227 reads the usage-recorded event with every required field of the run event envelope, and a second delivery of the same message identifier has no effect (ADR-0014 decisions 3 and 4, ADR-0024, ADR-0012). |
| AC3 | Given a workload token with the service scope that names the Metering service and no tenant claim, when the caller records usage for the tenant it forwards, then the forwarded tenant is admitted into the tenant context the endpoints require and the usage is counted for that tenant; without that scope the answer is 403, and a read of a usage meter of another tenant is answered 404 (ADR-0015 amendments on workload tokens and on a resource of another tenant). |
| AC4 | Given the allowed dimension option of the profile with a list of keys and units, when the service starts, then the list is bound and validated and an empty or malformed list refuses the start; a meter is provisioned and a usage is recorded for a listed key, a usage for another key is refused with 400 and changes nothing, and the meter of a listed dimension returns its unit (ADR-0020 decision 2, model/services/control-plane/CostUsageService.yaml). |
| AC5 | Given a generation without UseFactoryProfile, when its tests run, then the events carry the envelope base of the template with the added occurredOn on the MassTransit topology with unchanged topics, a dimension stays a free string, and the output of the default case equals the output before this PBI apart from that field and the work of the earlier PBIs (ADR-0028 amendment on the Factory profile switch, model/template-parameters/connectsoft-saas-metering.yaml). |
| Traces: services | CostUsageService |
| Traces: descriptors | run-event-envelope-v1 |
| Traces: adrs | ADR-0012, ADR-0014, ADR-0015, ADR-0020, ADR-0024, ADR-0028 |
| Depends on | AIFACTORY-US-279, AIFACTORY-US-280, AIFACTORY-US-281, feature:component-base-template-factory-profile, feature:contracts-package |
| Sources | model/components.yaml, model/template-parameters/connectsoft-saas-metering.yaml, model/services/control-plane/CostUsageService.yaml, docs/reference/schemas/run-event-envelope.schema.json, docs/reference/event-envelope.md, docs/architecture/adr/0014-run-and-lifecycle-envelopes.md, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1264 Base-template submodule moved to the base template with the Factory profile and the package snapshot regenerated |
operations | The base-template submodule of the Metering template points at the base template that carries UseFactoryProfile and the Orleans value of MessagingModelType, the template metadata of connectsoft-saas-metering offers both, build/MaterializedDirectory.Packages.props is regenerated and its check passes; no file inside the submodule is edited. |
ConnectSoft.Saas.MeteringTemplate |
AIFACTORY-TASK-608 Accepted envelope on the metering events |
implementation | The envelope base of every integration event of the template is completed with occurredOn, and the usage record and the usage-recorded body gain the optional run identifier; under UseFactoryProfile the events keep that base on the wire and are published through the outbox of the Orleans messaging profile; the events page records the mapping table onto the run event envelope (ADR-0014) that AIFACTORY-US-227 applies on receipt, so the usage reconciliation of the Factory (TASK-363) correlates by run and tenant; without the parameter the events change only by the added field. |
ConnectSoft.Saas.MeteringTemplate |
AIFACTORY-TASK-1298 Forwarded tenant of a workload token admitted into the tenant context |
implementation | Under UseFactoryProfile the tenant a caller forwards is admitted into the tenant context the REST endpoints and the gRPC services require when the validated workload token holds the service scope that names the Metering service and no tenant claim; a workload token without that scope is refused with 403, and a user token keeps the tid claim as its only source of the tenant. |
ConnectSoft.Saas.MeteringTemplate |
AIFACTORY-TASK-1299 Allowed dimension option of the Factory profile with key and unit |
contract | The options project declares the allowed dimension option with one entry per dimension, its key and its unit, and its validator; the provisioning and record contracts document the 400 answer for a key outside the list, the meter response carries the unit, and the configuration page of the template describes the option and that it is bound only under UseFactoryProfile. |
ConnectSoft.Saas.MeteringTemplate |
AIFACTORY-TASK-1300 Allowed dimensions bound at start and enforced on provisioning and recording |
implementation | Under UseFactoryProfile the allowed dimension option is bound and validated at start and an empty or malformed list refuses the start; EnsureUsageMeterProvisionedRequest and the record path accept only a listed key and refuse another with 400 before any counter changes; without the profile the dimension stays a free string. |
ConnectSoft.Saas.MeteringTemplate |
AIFACTORY-TASK-1265 Golden files, the mapped consumer test on the Orleans inbox, the workload scope tests and the allowed dimension tests |
fixture | The acceptance suite of the Factory case holds a golden JSON file per event in the envelope base of the template, a consumer that applies the mapping and reads a usage-recorded event from the Orleans inbox with every required field of the run event envelope, a duplicate delivery test, a rollback test, tests of a workload token with and without the service scope and of a read across tenants, and tests of the allowed dimension option with a listed key, another key and an empty list. | ConnectSoft.Saas.MeteringTemplate |
AIFACTORY-TASK-1266 Verify the envelope on the Factory profile and the unchanged default |
verification | Generate the template with UseFactoryProfile and without it, build both in Release and run their tests; the golden file, mapped consumer, duplicate, rollback, scope and allowed dimension tests pass on the Factory case and the default case keeps its envelope base and topics, which proves AC1 to AC5 of AIFACTORY-US-282 (ADR-0014, ADR-0028). |
ConnectSoft.Saas.MeteringTemplate |
AIFACTORY-US-283: SaaS Metering template: the packed template passes the default case and the Factory profile case of the shared template pipeline, descriptor validated, before the package publishes¶
evidence · persona asset-maintainer
As an asset maintainer, I want every change of the Metering template gated by its generated cases, so that a package that would generate a service which counts a usage twice never reaches the feed.
This PBI is the gate of the feature. The estate gates its templates with the shared template pipeline of ConnectSoft.AzurePipelines (template-ci/v1), whose rollout ledger lists the Metering template as pending, and the template has no manifest for it yet. The amendment of ADR-0028 on the Factory profile switch has the shared pipeline admit one additional gating case per declared profile beside the default case. This PBI adopts the mechanism. A manifest build/template-ci.json declares the default case, generated with MassTransit as the template does today, and the Factory profile case, generated with UseFactoryProfile. The validator of the descriptor in each case is the descriptor drift test of AIFACTORY-TASK-1292, which compares the descriptor with the code and validates it against its schema. The script build/regenerate.ps1 is not that validator: without a Factory endpoint it only parses the descriptor as JSON, so it stays in the cases as the parse it is and decides nothing about drift. The manifest names the test filter of each case and the services it needs, SQL Server for the store and the outbox, the broker of the default case and a co-hosted silo for the Factory case. The template pipeline imports the shared installer jobs: the candidate is packed once and installed, each case is generated, its descriptor is validated by the drift test, the solution is restored and built in Release, its tests run with the discovery and completion checks, the idempotency, window, window query, quota contract, envelope and allowed dimension tests among them, and the dependency audit runs. A descriptor that differs from the code, a usage that is counted twice or an incomplete run fails the run with the case and the stage named, and the package is not published. Publication requires the complete reports of both cases bound to the candidate and pushes a version that is not yet on the ConnectSoft feed. This is an evidence PBI (D113): a template feature has no scenario, so the gate names what it proves through its ADRs, the requirement on release gates and its sources: the measurement of ADR-0020, the descriptor of ADR-0025 and the generated-solution gate the epic requires, before the metering integration feature exports the first usage.
Acceptance criteria
| AC1 | Given a change of the Metering template, when its template pipeline runs the shared installer jobs with build/template-ci.json, then the candidate is packed once and installed, the default case and the Factory profile case are generated, the descriptor of each is validated by the descriptor drift test against the code and against ConnectSoft.Saas.Metering.schema.json, each is restored and built in Release, its tests run with the discovery and completion checks against the services the manifest declares, the window query tests among them in both cases, and the dependency audit runs (FR-11, ADR-0025 decision 2, ADR-0028 amendment on the Factory profile switch). |
| AC2 | Given a planted extra descriptor property, which is valid JSON and passes the parse of build/regenerate.ps1, a planted removal of the deduplication index or an incomplete run, when the pipeline evaluates the run, then the descriptor drift test fails the first with the member named, the triple delivery test fails the second, and each run fails with the case and the stage named and the package is not published (FR-11, ADR-0020 decision 3). |
| AC3 | Given complete reports of both cases bound to the candidate, when the publication job runs, then the package is pushed to the ConnectSoft feed with a version that was not on it, a fresh install of that version generates a Metering service with UseFactoryProfile whose tests pass unchanged, and model/template-parameters/connectsoft-saas-metering.yaml lists the parameter after the next template inventory (ADR-0028, model/backlog/epics.yaml states the gate as the completion of the epic). |
| Traces: adrs | ADR-0020, ADR-0025, ADR-0028 |
| Traces: requirements | FR-11 |
| Depends on | AIFACTORY-US-279, AIFACTORY-US-280, AIFACTORY-US-281, AIFACTORY-US-282, AIFACTORY-US-288, feature:component-base-template-findings |
| Sources | model/components.yaml, model/backlog/epics.yaml, model/template-parameters/connectsoft-saas-metering.yaml, docs/architecture/catalogs/templates.md, docs/architecture/adr/0025-saas-descriptor-import.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1267 Shared template pipeline manifest of the Metering template with the default and the Factory profile cases |
operations | build/template-ci.json of the Metering template declares the package, the solutions and the tests, the default case and the Factory profile case with the descriptor drift test of AIFACTORY-TASK-1292 as the descriptor validator of each and build/regenerate.ps1 only as the parse of the descriptor, the test filter of each case, which includes the window query tests, and the required services SQL Server, the broker of the default case and a silo for the Factory case; azure-pipelines-template.yml imports the shared installer jobs. |
ConnectSoft.Saas.MeteringTemplate |
AIFACTORY-TASK-1268 Planted descriptor difference and planted double count for the gate |
fixture | Pipeline fixtures plant an extra descriptor property, which passes the parse of build/regenerate.ps1 and which the descriptor drift test must fail with the member named, and a removed deduplication index, which the triple delivery test must fail, and assert that each run fails at its stage with the case named and that publication is not reached. |
ConnectSoft.Saas.MeteringTemplate |
AIFACTORY-TASK-1269 Publication bound to the complete reports of both cases |
operations | The publication job of the template pipeline requires the complete reports of the default case and the Factory profile case bound to the candidate; a missing or failed stage, an incomplete report or a version that is already on the ConnectSoft feed refuses publication with the reason. | ConnectSoft.Saas.MeteringTemplate |
AIFACTORY-TASK-1270 Verify the gate of the Metering template on a green and on the planted runs |
verification | One green run publishes the package and a fresh install generates a Metering service with UseFactoryProfile whose tests pass; the two planted runs fail before publication; together they prove AC1 to AC3 of AIFACTORY-US-283 (FR-11, ADR-0020, ADR-0025). |
ConnectSoft.Saas.MeteringTemplate |
AIFACTORY-US-128: SaaS Metering template: idempotent usage, windows and the quota contract before usage export is delivered and proven on a generated solution¶
enabling · persona asset-maintainer
As an asset maintainer, I want SaaS Metering service to carry idempotent usage, windows and the quota contract before usage export, so that it serves usage meters and quotas (BC-05/BC-34) without later rework.
This is the integration PBI of the feature. With the idempotent usage record, the windows, the query of the usage records of a window, the quota contract with the inbound usage topic, the Factory profile of the events and the gate of the earlier PBIs, the Metering template generates a service the usage export of the Factory can rely on. An exporter records a usage with an idempotency key and may repeat the call: the counter grows once and the answer is the first result. The usage is counted in a window that follows the subscription period, a roll or the passed boundary of a Fixed window closes the window and opens the next, and the threshold and quota events name the window and the meter key Billing reads. A caller reads the usage records and the total of a window back, page by page. Usage reported on the registered inbound topic reaches the quota saga. A service generated with UseFactoryProfile publishes its events in the complete envelope base of the template through the Orleans messaging profile, a Factory consumer maps them onto the run event envelope on receipt, and the service counts only the dimensions its allowed dimension option lists; a service generated without the parameter keeps the envelope and the MassTransit topology of the template and a free dimension. The descriptor is held to the code by the descriptor drift test. The implementation lives in the tasks of the earlier PBIs; this PBI keeps the migrated verification of the feature. The feature is done when the packed template passes its default case and its Factory profile case in the shared template pipeline with the descriptor validated and the package is on the ConnectSoft feed, which is what the metering integration feature of this increment depends on before it exports the first usage record.
Acceptance criteria
| AC1 | Given the template repository ConnectSoft.Saas.MeteringTemplate with the work of this feature, when the template is packed, installed and instantiated in its pipeline, then the generated solution of every case builds and its tests pass before the package publishes with a verified version (ADR-0020, model/components.yaml). |
| AC2 | Given the work of AIFACTORY-TASK-605 (usage record with an idempotency key, saas-MET-F01) is done, then RecordUsage carries a usage record with a caller-supplied idempotency key, a repeated record with the same key changes no counter and returns the first result, and a test delivers the same record three times (ADR-0014 decision 3). |
| AC3 | Given the work of AIFACTORY-TASK-606 (window semantics aligned with the subscription period, saas-MET-F02) is done, then a counter belongs to a window, a roll or the passed boundary of a Fixed window closes the window and opens the next, threshold and quota events carry the window id, and a rating-window event from Billing opens the window the invoice period needs (ADR-0020 decision 3). |
| AC4 | Given the work of AIFACTORY-TASK-607 (quota contract aligned with Billing and the inbound usage topology, saas-MET-F03 and saas-MET-F04) is done, then the quota events carry the field Billing deserializes, proven by a contract test over golden files, and the UsageReportedForQuota inbound topic is registered in the topology and the descriptor so reported usage reaches the quota saga (ADR-0025 decision 2). |
| AC5 | Given the work of AIFACTORY-TASK-608 (accepted envelope on the metering events) is done, then every integration event of the template carries the complete envelope base with occurredOn, the usage-recorded body carries the run when the record names one, the events page records the mapping onto the run event envelope that the consuming Factory service applies on receipt, and under UseFactoryProfile the events leave through the outbox of the Orleans messaging profile, so the usage reconciliation of the Factory correlates by run and tenant; without the parameter the events change only by the added field (ADR-0014 amendment on envelopes per event family). |
| Traces: services | CostUsageService |
| Traces: adrs | ADR-0014, ADR-0020, ADR-0025 |
| Depends on | AIFACTORY-US-279, AIFACTORY-US-280, AIFACTORY-US-281, AIFACTORY-US-282, AIFACTORY-US-283, AIFACTORY-US-288 |
| Sources | model/components.yaml, model/services/control-plane/CostUsageService.yaml, docs/architecture/adr/0020-commercial-model.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1271 Gap backlog and gap analysis pages of the template record the closed items |
documentation | The gap backlog and the gap analysis pages of the template mark saas-MET-F01 to saas-MET-F04 as closed with the tests that prove each, state what UseFactoryProfile adds on top of them, and leave saas-MET-F05 to saas-MET-F09 as the open items they are. |
ConnectSoft.Saas.MeteringTemplate |
AIFACTORY-TASK-689 Verify saas-metering-template-delivered by running the declared command |
verification | Run dotnet build -c Release and dotnet test -c Release --no-build on the authoring solution and on the default and Factory profile cases generated from the published package; they pass and prove AC1 to AC5 of AIFACTORY-US-128. |
ConnectSoft.Saas.MeteringTemplate |