Skip to content

AIFACTORY-FEAT-102: Metering integration for usage accounting

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 · Build order 135 of 185 (Factory code)

Usage that CostUsageService records is exported to the SaaS Metering service in its units, so that budgets and invoices use one measurement. Component: SaaS Metering service (extend).

Delivers —
Stubs —
Realizes components: cmp-saas-metering
Requirements —
Depends on AIFACTORY-FEAT-164 SaaS Metering template: idempotent usage, windows and the quota contract before usage export
Sources model/components.yaml, docs/architecture/ecosystem-composition.md

AIFACTORY-US-289: Metering integration: the ServiceModel package of the Metering service offers a typed client for record usage and the window query with typed outcomes and is published to the ConnectSoft feed

enabling · persona asset-maintainer As an asset maintainer, I want a typed client for record usage and for the window query in the package the Metering service publishes its contracts in, so that CostUsageService reaches the Metering service by a version pin and no Factory repository writes its own client or copies a contract.

The REST page of the Metering template states that the contracts and the typed client facades of the service live in the package ConnectSoft.Saas.Metering.ServiceModel. The project holds requests, responses and the two service interfaces today and no client facade, and the service model pipeline of the template, azure-pipelines-service-model.yml, has a build, a pack and a push step and no test. CostUsageService must reach the Metering service by a version pin and without copying a type, and it can pin only what is on the feed, so the package has to be published before the export is built. The Tenants integration has a PBI for exactly this (AIFACTORY-US-255), and this PBI follows it. It adds a client facade to the package for REST and for the code first gRPC client with three operations: record usage with its idempotency key, the query of the usage records and the total of one window that AIFACTORY-US-288 of the feature component-saas-metering-template declares, and its list of closed windows. The facade takes the transport the consumer configured, with the workload token of the consumer, the forwarded tenant and the propagation of correlation and trace context, and adds no authentication, no retry and no cache of its own. It returns typed outcomes and never an exception for an answer of the service: the recorded usage with its window and the start of that window, the conflict of a key with a different quantity with both quantities, the refusal of an invalid record or of a dimension that is not allowed with the reason, the unknown window, and the failure to reach the service, which is never turned into one of the others. Contract tests in the template run the facade against a Metering service generated from the packed template over both transports, so that the client and the service cannot drift apart inside one package version. The service model pipeline gains a test step that runs them, publishes the package to the ConnectSoft feed only after they pass and refuses a version that is already on the feed. The published version is recorded on the documentation of the template, because the model of this repository holds no package versions.

Acceptance criteria

AC1 Given the client facade of the ServiceModel package and a Metering service generated from the packed template, when a usage is recorded three times with one idempotency key over REST and over gRPC, then every call returns the typed recorded outcome with the same window and its start and the service counted once; a record with the same key and another quantity returns the typed conflict with both quantities, and an invalid record or a dimension outside the allowed list returns the typed refusal with the reason (ADR-0014 decision 3, ADR-0020 decision 2).
AC2 Given usage records in a closed window, when the facade queries the window and lists the closed windows over both transports, then it returns the pages, the total and the windows as the service holds them, an unknown window and a window of another tenant are the typed unknown window, and a service that cannot be reached is the typed failure and never an empty window (ADR-0020 decision 3, ADR-0015 amendment on a resource of another tenant).
AC3 Given the facade, when a consumer configures its transport with a workload token, a forwarded tenant and trace context, then the call carries all three unchanged, the facade holds no cache, no retry and no credential, and the contract tests of the template fail when the facade and the service contract differ (ADR-0028, ADR-0015 amendment on workload tokens).
AC4 Given the service model pipeline of the Metering template, when it runs, then the package builds, the contract tests of the facade pass in its test step, and the package is published to the ConnectSoft feed; a failing test or a version that is already on the feed refuses publication with the reason, and the documentation of the template records the published version (FR-11, ADR-0028, model/components.yaml).
Traces: adrs ADR-0014, ADR-0015, ADR-0020, ADR-0028
Traces: requirements FR-11
Depends on feature:component-saas-metering-template
Sources model/components.yaml, docs/architecture/ecosystem-composition.md, docs/architecture/adr/0020-commercial-model.md, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-1301 Typed client facade for record usage and the window query over REST and gRPC in the ServiceModel package implementation The package ConnectSoft.Saas.Metering.ServiceModel holds a client facade for REST and for the code first gRPC client with record usage, the query of the usage records of a window and the list of closed windows, and typed outcomes for the recorded usage with its window, the conflict, the refusal, the unknown window and the failure; it takes the configured transport of the consumer and holds no cache, retry or credential. ConnectSoft.Saas.MeteringTemplate
AIFACTORY-TASK-1302 Contract tests of the facade against a service generated from the packed template fixture Tests of the template run the facade against a Metering service generated from the packed template over both transports for a triple delivery, a conflict, an invalid record, a dimension that is not allowed, a closed window with several pages, a window of another tenant and a stopped service, and assert the typed outcome of each. ConnectSoft.Saas.MeteringTemplate
AIFACTORY-TASK-1282 ServiceModel package of the Metering service tested and published with a version guard operations azure-pipelines-service-model.yml of the Metering template gains a test step that runs the contract tests of the facade, publishes ConnectSoft.Saas.Metering.ServiceModel with the idempotent record contract, the window query and the typed client to the ConnectSoft feed only after the tests pass, refuses a version that is already on the feed, and the documentation of the template records the published version. ConnectSoft.Saas.MeteringTemplate
AIFACTORY-TASK-1303 Verify the typed outcomes of the facade and the published package verification Run the contract tests of the facade and one run of the service model pipeline; the seven cases return their typed outcomes over both transports, the package is on the ConnectSoft feed and a second run with the same version is refused, which proves AC1 to AC4 of AIFACTORY-US-289 (FR-11, ADR-0020). ConnectSoft.Saas.MeteringTemplate

AIFACTORY-US-284: Metering integration: the seven Factory meters are dimensions of the Metering service with declared units, and CostUsageService reaches the service through its pinned ServiceModel client

enabling · persona operator As an operator, I want every Factory meter to have one dimension and one unit in the Metering service, so that a quantity the Factory observed means the same in a budget and in an invoice.

CostUsageService records usage on seven meters, ModelTokens, RunsAccepted, RunsCompleted, ToolInvocations, SandboxMinutes, StorageGb and ProductCapacity, each with a decimal quantity, a pricing revision and a status (model/services/control-plane/CostUsageService.yaml). The Metering service counts a delta per tenant and dimension, and its counter and its delta are 64 bit integers. ADR-0020 decision 2 implements the commercial model by extending the SaaS templates so that budgets and invoices read one measurement, and docs/architecture/ecosystem-composition.md lists Factory-specific meters among what the SaaS services need once their gaps are closed. Nothing states today which dimension and which unit a Factory meter is, or how CostUsageService reaches the Metering service. This PBI settles both. A meter map in CostUsageService holds, for every value of the Meter enumeration, the dimension key of the Metering service, the unit of that dimension and the factor that converts the Factory quantity into it. Because the counter is an integer, the unit of each dimension is its smallest whole unit, so that a decimal quantity of the Factory becomes a whole number of units. A meter without an entry stops the service at start with the meter named. A quantity the factor cannot express as a whole number of the unit is never rounded: its export row takes the state Refused with the reason that the conversion is not exact, nothing is sent, and the row is listed by the meter reconciliation. The Metering template has no registry of dimensions; under UseFactoryProfile it binds the allowed dimension option that AIFACTORY-US-282 of the feature component-saas-metering-template delivers behind the gate of the template, and refuses usage for a key outside it. This PBI changes nothing in the template, so the template does not pass its gate a second time: the seven entries of the map, key and unit, become the configuration of that option in the repository ConnectSoft.AI.SoftwareFactory.MeteringService, where AIFACTORY-US-290 scaffolds, configures and deploys the Factory instance of the Metering service (D115). The concrete unit and conversion factor of each of the seven dimensions are an owner input; this PBI fixes the rule and the shape of the map and names no value. CostUsageService takes the contracts and the typed client of the Metering service from the package ConnectSoft.Saas.Metering.ServiceModel at the version AIFACTORY-US-289 published, and copies no type. It calls with its workload token, which carries a service scope and no tenant claim, and forwards the tenant of the usage record; the Metering service admits that tenant only because the token holds the service scope that names it. The model lists the library ConnectSoft.Extensions.Saas.Metering for the service; its README describes marker interfaces for tenant scoped metering adapters, and the export adapter of this feature implements them, so the entry of the model stays; CostUsageService does not host that library as its meter store, because the meter store is the Factory Metering service behind the typed client (D115). A Factory tenant is the tenant of the Factory instance of the Metering service; the meters of a generated product live in the stores of the product (ADR-0020 decision 4) and are not touched here.

Acceptance criteria

AC1 Given the meter map of CostUsageService, when the service starts, then every value of the Meter enumeration of model/services/control-plane/CostUsageService.yaml has a dimension key, a unit that is the smallest whole unit of the dimension and a conversion factor, and a meter without an entry stops the start with the meter named; a quantity that is no whole number of its unit after conversion is not rounded and its export row becomes Refused with the reason that the conversion is not exact (ADR-0020 decision 2).
AC2 Given a Metering service generated with UseFactoryProfile whose allowed dimension option holds the seven entries of the meter map, when the service starts and its meters are read, then the seven Factory dimensions are accepted with the units of the meter map, and a usage for a dimension outside them is refused with 400; a contract test compares the keys and units the service returns with the map and fails on a difference, and the same seven entries are the configuration of the Factory instance that AIFACTORY-US-290 deploys (ADR-0020 decision 2, docs/architecture/ecosystem-composition.md).
AC3 Given CostUsageService with the ServiceModel package at the version AIFACTORY-US-289 published, when it calls the Metering service, then it uses the typed client with a workload token that carries the service scope and no tenant claim and forwards the tenant of the usage record, its export adapter implements the tenant scope marker interfaces of ConnectSoft.Extensions.Saas.Metering, and an architecture test finds no copied contract type of the Metering service in the solution (ADR-0015 amendment on workload tokens, ADR-0028).
Traces: services CostUsageService
Traces: adrs ADR-0015, ADR-0020, ADR-0028
Depends on AIFACTORY-US-289, feature:component-saas-metering-template, feature:cost-usage-service-complete
Sources model/components.yaml, model/services/control-plane/CostUsageService.yaml, docs/architecture/ecosystem-composition.md, docs/architecture/adr/0020-commercial-model.md, docs/architecture/commercial-model.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-1272 Meter map of the seven Factory meters with dimension, unit and factor contract CostUsageService holds a validated meter map with one entry per value of the Meter enumeration: the dimension key, the unit, which is the smallest whole unit of the dimension because the Metering counter is an integer, and the conversion factor; start fails on a missing entry with the meter named, and a conversion that gives no whole number of the unit is refused and never rounded; the map is documented on the service page. ConnectSoft.AI.SoftwareFactory.CostUsageService
AIFACTORY-TASK-1273 Pinned ServiceModel client of the Metering service with the workload token implementation CostUsageService references ConnectSoft.Saas.Metering.ServiceModel at the version AIFACTORY-US-289 published, registers the typed client facade with the workload token of the service and the forwarding of the tenant, its export adapter implements the tenant scope marker interfaces of ConnectSoft.Extensions.Saas.Metering, and an architecture test fails on a contract type of the Metering service declared in the solution. ConnectSoft.AI.SoftwareFactory.CostUsageService
AIFACTORY-TASK-1274 Verify the meter map against the seeded dimensions verification Run the contract test of CostUsageService against a Metering service generated with UseFactoryProfile and configured with the entries of the meter map; the map and the allowed dimensions agree, a usage for an unknown dimension is refused, a quantity that is no whole number of its unit is refused and not rounded, and the architecture test passes, which proves AC1 to AC3 of AIFACTORY-US-284 (ADR-0020, model/services/control-plane/CostUsageService.yaml). ConnectSoft.AI.SoftwareFactory.CostUsageService

AIFACTORY-US-290: Metering integration: the Factory Metering service is scaffolded from the pinned Metering template into its own repository, configured with the seven Factory dimensions and deployed alone

enabling · persona operator As an operator, I want the Metering service of the Factory to run as its own service from its own repository, generated from a pinned version of the Metering template, so that the meters that budgets and invoices read live in one service that deploys and fails on its own and that CostUsageService reaches only through its typed client.

The Factory runs its own Metering service from increment I4 (D115). model/components.yaml records it on the component: the instance is scaffolded from the Metering template into the repository ConnectSoft.AI.SoftwareFactory.MeteringService and has its own deployable, as ADR-0028 decision 1 requires of every Factory service, and model/services/control-plane/CostUsageService.yaml names it as the meter store that CostUsageService calls through the typed client. CostUsageService does not host the metering library as its store. No earlier PBI creates this instance: the acceptance suite of AIFACTORY-US-287 generates a service of its own for the proof and discards it. This PBI creates the repository with the scaffold command of ADR-0028 and its amendment on the Factory profile switch, dotnet new connectsoft-saas-metering -n ConnectSoft.AI.SoftwareFactory.MeteringService --UseFactoryProfile true, from the template package at the version the gate of the feature component-saas-metering-template published (AIFACTORY-US-283). The generated output is committed unchanged: the idempotent record, the windows, the window query, the allowed dimension option, the admission of a forwarded tenant and the outbox of the Orleans messaging profile are work of the template feature and are not rewritten in the repository. The repository records the version of the template package it was generated from and the version of ConnectSoft.Saas.Metering.ServiceModel that belongs to it, which is the version CostUsageService pins, so that the client and the service are one contract version and a later regeneration starts from a known template. The instance is configured in its own repository: the allowed dimension section holds the seven entries, key and unit, of the meter map of AIFACTORY-US-284, and the service binds and validates the section at start. The units and factors themselves are an owner input to that map and are not chosen here. The pipeline of the repository builds and tests the solution and publishes the service as its own deployable; it is deployed as its own workload from the Kubernetes manifests and the Helm chart the template generates (the Deployment page of the template), with its own relational store, its own messaging service name and its own transport credential, as ADR-0028 decisions 5 and 7 require. The service serves the liveness and the readiness endpoint of a generated Factory service: liveness answers alive, and readiness answers ready only after the store is migrated and the Orleans messaging profile has started, and names the dependency while it is unready. A start with an empty or malformed allowed dimension section is refused with the reason, a usage for a dimension outside the seven is refused with 400, and a caller whose workload token lacks the service scope that names the Metering service is answered 403. A Factory tenant is a tenant of this instance; the meters of a generated product live in the stores of the product (ADR-0020 decision 4) and are not touched.

Acceptance criteria

AC1 Given the Metering template package at the version the gate of the feature component-saas-metering-template published, when the repository ConnectSoft.AI.SoftwareFactory.MeteringService is created with dotnet new connectsoft-saas-metering -n ConnectSoft.AI.SoftwareFactory.MeteringService --UseFactoryProfile true, then the generated output is committed unchanged, the solution builds and its tests pass in the pipeline of the repository, and the repository records the template version it was generated from and the version of ConnectSoft.Saas.Metering.ServiceModel that belongs to it (ADR-0028 decision 1 and its amendment on the Factory profile switch, model/components.yaml).
AC2 Given the pipeline of the repository, when it runs, then the service is published as its own deployable and deployed as its own workload with its own relational store, its own messaging service name and its own transport credential, and no other Factory service hosts the Metering service or the metering library as a meter store: CostUsageService reaches it only through the typed client (ADR-0028 decisions 1, 5 and 7, model/services/control-plane/CostUsageService.yaml).
AC3 Given the deployed instance, when its liveness and readiness endpoints are probed, then liveness answers alive and readiness answers ready only after the store is migrated and the Orleans messaging profile has started, and names the dependency while it is unready; a start with an empty or malformed allowed dimension section is refused with the reason (ADR-0028 consequences on health and readiness per service, ADR-0020 decision 2).
AC4 Given the instance configured with the seven entries of the meter map of model/services/control-plane/CostUsageService.yaml, when CostUsageService records usage with its workload token and a forwarded tenant, then a usage of one of the seven dimensions is counted for that tenant in the unit of the map, a usage for another dimension is refused with 400, and a caller without the service scope that names the Metering service is answered 403 (ADR-0020 decision 2, ADR-0015 amendment on workload tokens).
Traces: services CostUsageService
Traces: adrs ADR-0015, ADR-0020, ADR-0028
Depends on AIFACTORY-US-284, feature:component-saas-metering-template, feature:cost-usage-service-complete
Sources model/components.yaml, model/services/control-plane/CostUsageService.yaml, model/template-parameters/connectsoft-saas-metering.yaml, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, docs/architecture/adr/0020-commercial-model.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-1305 Create the repository ConnectSoft.AI.SoftwareFactory.MeteringService and scaffold it from the Metering template with the Factory profile implementation The repository exists, the output of dotnet new connectsoft-saas-metering -n ConnectSoft.AI.SoftwareFactory.MeteringService --UseFactoryProfile true from the template package at the version the gate of AIFACTORY-US-283 published is committed unchanged, the solution builds and the tests of the generated solution pass in the repository pipeline; the documentation of the repository records the template version it was generated from and the version of ConnectSoft.Saas.Metering.ServiceModel that belongs to it, which is the version CostUsageService pins (AIFACTORY-TASK-1273). ConnectSoft.AI.SoftwareFactory.MeteringService
AIFACTORY-TASK-362 The seven Factory dimensions supplied to the allowed dimension option of the Metering service implementation The repository of the Factory Metering service holds the configuration section of the allowed dimension option that AIFACTORY-TASK-1299 of the Metering template declares, with the seven entries, dimension key and unit, of the meter map of CostUsageService (AIFACTORY-TASK-1272), so that usage records are exported in the units the Metering service holds; the instance binds and validates the section at start, and a test of the repository starts the service with the section and reads the seven dimensions with their units; the units are the ones the owner supplies for the map and none is chosen by this task; no file of the Metering template changes. ConnectSoft.AI.SoftwareFactory.MeteringService
AIFACTORY-TASK-1306 Pipeline and deployment of the Factory Metering service as its own workload operations The pipeline of the repository builds and tests the solution, publishes the container image of the service and deploys it as its own workload from the Kubernetes manifests and the Helm chart the template generates, with its own relational store, its own messaging service name and its own transport credential; the deployment probes the liveness and the readiness endpoint of the service, and no other Factory service shares its process or its database (ADR-0028 decisions 1, 5 and 7). ConnectSoft.AI.SoftwareFactory.MeteringService
AIFACTORY-TASK-1307 Verify the deployed Factory Metering service by its health, its dimensions and its scope check verification Probe the deployed instance: liveness answers alive and readiness answers ready after the store is migrated; a start with an empty allowed dimension section is refused with the reason; the contract test of CostUsageService from AIFACTORY-US-284, run against the instance, finds the seven dimensions and units equal to the meter map; a usage for another dimension is refused with 400 and a call without the service scope is answered 403; the recorded template version equals the version of the published gate; which proves AC1 to AC4 of AIFACTORY-US-290 (ADR-0028, ADR-0020). ConnectSoft.AI.SoftwareFactory.MeteringService

AIFACTORY-US-285: Metering integration: every settled usage record of CostUsageService is exported once to the Metering service in its units, and an outage leaves the record pending

behavior · persona operator As an operator, I want settled usage to reach the Metering service once, whatever fails on the way, so that the meters a tenant is billed from hold exactly what the Factory observed.

An export worker of CostUsageService carries settled usage to the Metering service. A usage record is settled when its status is Observed, which CostUsageService/UsageRecorded announces, or Reconciled, which CostUsageService/UsageReconciled announces for a record that was Estimated or Uncertain; ADR-0020 decision 3 keeps unknown usage uncertain until it is reconciled, so an Estimated or Uncertain record is not exported, and a Reserved amount is not usage. When a CostUsageService/UsageRecord becomes settled, an export row in state Pending is written in the same transaction. The worker reads pending rows partitioned by tenant, converts the quantity by the meter map, and records the usage through the typed client of the Metering service with the usage identifier as the idempotency key, the time of occurrence of the record and the run it was metered for as its source and run identifier. A quantity that is no whole number of the unit of its dimension is not sent: the row is marked Refused with the reason that the conversion is not exact. On success the worker marks the row Exported and stores on it the window the Metering service reports for the usage and the start of that window. The Metering service counts a usage in the window that is open when it is recorded, so a record exported after the window of its period was rolled sits in the next window. The worker does not hide that shift: when the time of occurrence of the record precedes the start of the reported window, the row is marked late, and the meter reconciliation lists it. The call is repeatable: a crash between the call and the mark leads to a second call under the same key, which the Metering service answers with the first result and counts nowhere. When the Metering service cannot be reached the row stays Pending, the worker retries with exponential backoff, and nothing is marked exported. When the Metering service answers that the key exists with a different quantity, the row is marked as a conflict with both quantities and left for the meter reconciliation; the worker never sends a correction on its own. When the Metering service refuses the usage as invalid, the row is marked Refused with the reason and is not retried until it is changed. The worker records the attempts of each row and publishes the count and the age of pending rows as metrics, so that an export that falls behind is seen before a period closes.

Acceptance criteria

AC1 Given a CostUsageService/UsageRecord that became Observed and was announced by CostUsageService/UsageRecorded, when the export worker runs, then one usage exists in the Metering service for the tenant and the dimension of the meter with the converted quantity, the time of occurrence and the usage identifier as its key, and the export row is Exported with the window the Metering service reports for it and the start of that window; a record whose time of occurrence precedes that start is counted in the open window and its row is marked late (ADR-0020 decision 2).
AC2 Given a usage record in status Estimated or Uncertain, when the export worker runs, then nothing is exported for it; when CostUsageService/UsageReconciled confirms the record, then it is exported once with the confirmed quantity (ADR-0020 decision 3, FR-09).
AC3 Given an export whose call succeeded and whose mark was lost, when the worker runs again, then the second call under the same key adds no usage and no meter in the Metering service and the row becomes Exported (ADR-0014 decision 3).
AC4 Given the Metering service is unreachable, when the export worker runs, then the rows stay Pending, the worker retries with backoff, nothing is marked exported, and the count and the age of pending rows are published as metrics of the service (ADR-0020 decision 3, NFR-12).
AC5 Given the Metering service answers a conflict for a key with a different quantity or refuses a usage as invalid, or the quantity of a record is no whole number of the unit of its dimension, when the worker handles the row, then it is marked as a conflict or as Refused with the reason, it is not retried unchanged, no counter of the Metering service is rewritten, and the row is reported by the meter reconciliation (ADR-0014 decision 3, FR-09).
Traces: services CostUsageService
Traces: aggregates CostUsageService/UsageRecord
Traces: events CostUsageService/UsageRecorded, CostUsageService/UsageReconciled
Traces: adrs ADR-0014, ADR-0020
Traces: requirements FR-09
Relates: nfrs NFR-12
Depends on AIFACTORY-US-284, feature:cost-usage-service-complete, feature:component-saas-metering-template
Sources model/components.yaml, model/services/control-plane/CostUsageService.yaml, docs/architecture/adr/0020-commercial-model.md, docs/reference/schemas/usage-record.schema.json

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-1275 Export state of a usage record in the store of CostUsageService migration A migration adds the export table to the store of the service: one row per settled usage record with the state Pending, Exported, Conflict or Refused, the attempts, the reason, the window the Metering service reported with its start and the late mark; the Pending row is written in the transaction that settles the record; mapping tests run against an isolated test database. ConnectSoft.AI.SoftwareFactory.CostUsageService
AIFACTORY-TASK-1276 Export worker with the usage identifier as the idempotency key implementation A worker of the service reads pending rows partitioned by tenant, converts the quantity by the meter map and refuses a conversion that is not exact, records the usage through the typed client with the usage identifier as the key, marks the row Exported with the reported window and its start and marks it late when the time of occurrence precedes that start, keeps it Pending with exponential backoff while the Metering service is unreachable, and marks a conflict or a refusal with its reason; a duplicate trigger has no second effect and the pending count and age are metrics of the service. ConnectSoft.AI.SoftwareFactory.CostUsageService
AIFACTORY-TASK-1277 Export tests for the lost mark, the outage, the conflict, the refusal, the inexact conversion and the late record fixture Acceptance tests of the service against a stub of the Metering contract cover an Observed record, an Uncertain record that is reconciled later, a call whose mark is lost, an outage with retries, a conflict on the key, a refused usage, a quantity that is no whole number of its unit and a record whose window was rolled before its export, and assert the export rows, the late mark and the calls the stub received. ConnectSoft.AI.SoftwareFactory.CostUsageService
AIFACTORY-TASK-1278 Verify the export of settled usage verification Run dotnet test -c Release --filter Category=Acceptance on CostUsageService; a zero-match filter counts as a failure; the export tests pass and prove AC1 to AC5 of AIFACTORY-US-285, that is the single export after CostUsageService/UsageRecorded and CostUsageService/UsageReconciled, the repeat without a duplicate and the pending rows under an outage. ConnectSoft.AI.SoftwareFactory.CostUsageService

AIFACTORY-US-286: Metering integration: Factory usage and metered usage are compared per tenant and window, every difference is listed with its record identifiers, and a clean window is marked reconciled

behavior · persona operator As an operator, I want a comparison of what the Factory observed with what the Metering service counted, window by window, so that a difference is found and named before an invoice is drawn from the meters.

The model of CostUsageService has a reconciliation worker that confirms estimated and uncertain usage from provider statements. This PBI delivers a different comparison, the meter reconciliation: per tenant, dimension and window of the Metering service, the settled usage records the Factory holds are compared with the usage records the Metering service holds. A scheduled worker of CostUsageService asks the Metering service for the windows of every tenant and dimension that closed since its last run, reads the usage records and the total of each window through the window query that AIFACTORY-US-288 of the feature component-saas-metering-template delivers, by the typed client of AIFACTORY-US-289, and compares them with the CostUsageService/UsageRecord rows whose export row names the window. It lists four kinds of difference, each with the identifiers of the records involved: a record the Factory exported that the Metering service does not hold, a usage in the Metering service under a key the Factory does not know, a quantity that differs after conversion by the meter map, and a row that is still Pending, in conflict or refused. It lists a fifth kind of finding that is no difference: a late record, one whose export row is marked late because its time of occurrence precedes the start of the window it was counted in. Both stores agree on a late record, so it does not block the state Reconciled; it is listed so that an operator sees which usage of an earlier period the measurement of this window contains, since ADR-0020 has budgets and invoices read one measurement per period. The result is stored per tenant and window with the state Reconciled or Differs, the list of differences and the list of late records, written as a structured log record and counted on a metric. Nothing is repaired: the worker rewrites no counter and no usage record in either store, because a difference is a finding for an operator and a correction is a new usage record with its own receipt. A window with a pending export is never marked reconciled. A second run for the same tenant and window replaces the stored result and has no other effect, so a window becomes Reconciled once its last pending row is exported. When the Metering service cannot be reached the run of that tenant fails, is retried, and records no result. The service has no modelled read operation for the result; an operator reads it from the log and the metric until the model gains one, which is reported as a gap of the model.

Acceptance criteria

AC1 Given a closed window of a tenant in which every settled CostUsageService/UsageRecord was exported and the Metering service holds the same records and total, when the meter reconciliation runs, then the window is stored as Reconciled with an empty list of differences (FR-09, ADR-0020 decision 3).
AC2 Given a window with a record missing in the Metering service, a usage under an unknown key and a quantity that differs, when the reconciliation runs, then the window is stored as Differs and each difference is listed with its kind, the usage identifiers and both quantities, and no counter and no usage record is rewritten in either store (FR-09, ADR-0020 decision 3).
AC3 Given a window with an export row that is Pending, in conflict or refused, when the reconciliation runs, then the window is not marked Reconciled and the row is listed; when the row is exported and the reconciliation runs again, then the stored result of that window is replaced by Reconciled and nothing else changes (ADR-0014 decision 3, model/services/control-plane/CostUsageService.yaml).
AC4 Given the Metering service cannot be reached, when the reconciliation of a tenant runs, then the run fails and is retried, no result is stored for the window, and an earlier stored result is left as it was (ADR-0020 decision 3, NFR-12).
AC5 Given a closed window that holds a record whose export row is marked late, because its time of occurrence precedes the start of the window it was counted in, when the reconciliation runs, then the record is listed as a late record with its usage identifier, its time of occurrence and the window, and the window is still stored as Reconciled when it has no difference (ADR-0020 decision 3, FR-09).
Traces: services CostUsageService
Traces: aggregates CostUsageService/UsageRecord
Traces: events CostUsageService/UsageRecorded, CostUsageService/UsageReconciled
Traces: adrs ADR-0014, ADR-0020
Traces: requirements FR-09
Relates: nfrs NFR-12
Depends on AIFACTORY-US-285, AIFACTORY-US-289, feature:cost-usage-service-complete, feature:component-saas-metering-template
Sources model/components.yaml, model/services/control-plane/CostUsageService.yaml, docs/architecture/adr/0020-commercial-model.md, docs/architecture/commercial-model.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-1279 Result and difference shape of the meter reconciliation contract The service declares the stored result of a meter reconciliation, tenant, dimension, window, state Reconciled or Differs, the list of differences and the list of late records, the four difference kinds with the usage identifiers and quantities each carries, and the late record finding that does not change the state; a migration adds its table and the service page documents the shape and that nothing is repaired. ConnectSoft.AI.SoftwareFactory.CostUsageService
AIFACTORY-TASK-363 Reconciliation of metered usage with the usage of the Factory implementation A scheduled worker reads the closed windows and their usage records through the typed client of the Metering service, compares the meters with the usage records per tenant, dimension and closed window, reports every difference with its record identifiers, lists late records without counting them as a difference, stores the window as Reconciled or Differs, never marks a window with a pending export as reconciled, rewrites nothing in either store and is idempotent per tenant and window. ConnectSoft.AI.SoftwareFactory.CostUsageService
AIFACTORY-TASK-1280 Reconciliation tests for a clean window, the four differences, a late record and an outage fixture Acceptance tests of the service against a stub of the Metering contract cover a clean window, each of the four difference kinds, a window with a late record that stays Reconciled, a window that becomes clean after its pending row is exported, a repeated run and an unreachable Metering service, and assert the stored results and that neither store was rewritten. ConnectSoft.AI.SoftwareFactory.CostUsageService
AIFACTORY-TASK-1281 Verify the meter reconciliation verification Run dotnet test -c Release --filter Category=Acceptance on CostUsageService; a zero-match filter counts as a failure; the reconciliation tests pass and prove AC1 to AC5 of AIFACTORY-US-286 (FR-09, ADR-0020). ConnectSoft.AI.SoftwareFactory.CostUsageService

AIFACTORY-US-287: Metering integration: export and reconciliation pass against a Metering service generated from the published template, with the published ServiceModel package and no stub between the two services

evidence · persona operator As an operator, I want the export and the reconciliation proven against a real Metering service and not only against a stub, so that the two services cannot drift apart between the version one publishes and the version the other pins.

This PBI is the proof of the feature across the two repositories. The package ConnectSoft.Saas.Metering.ServiceModel with the idempotent record contract, the window query and the typed client is on the ConnectSoft feed through AIFACTORY-US-289, and CostUsageService pins that version. Its acceptance suite then runs against a Metering service that the suite generates from the published template package with UseFactoryProfile, configures with the seven allowed dimensions of the meter map and hosts in the acceptance environment, with no stub between the two: a set of settled usage records is exported twice and the Metering service holds each once; the Metering service is stopped during an export and the records stay pending and arrive after it returns; a window is rolled and reconciled clean through the window query of the generated service; a record whose window was rolled before its export is counted in the open window, marked late and listed without blocking the reconciled state; a usage planted in the Metering service under an unknown key is listed as a difference. Neither service is built from a project reference to the other: both restore what they need from the feed. The PBI proves that budgets and invoices read one measurement, as ADR-0020 decides, the reservation and reconciliation requirement FR-09 for the pair of services, and the release gate of FR-11 for the pair of published versions.

Acceptance criteria

AC1 Given CostUsageService with the ServiceModel package at the version AIFACTORY-US-289 published and a Metering service that the acceptance suite generates from the published template package with UseFactoryProfile, when the suite starts, then both restore from the ConnectSoft feed without a project reference to each other and the Metering service accepts the seven allowed dimensions of the meter map (FR-11, ADR-0028, model/components.yaml).
AC2 Given that pair of services, when a set of settled usage records is exported twice, then the Metering service holds each record once with the quantity, the unit, the tenant and the window the Metering service reports for it, stored on the export row, and a stop of the Metering service during an export leaves the records pending until it returns (FR-09, ADR-0020 decision 2).
AC3 Given the same pair of services, when a window is rolled and the meter reconciliation runs, then the window is Reconciled; when a record whose window was rolled before its export is exported, then it is counted in the open window, marked late and listed as a late record while that window stays Reconciled; when a usage is planted in the Metering service under an unknown key and the reconciliation runs again, then the window Differs and the planted usage is listed (FR-09, docs/architecture/ecosystem-composition.md).
Traces: adrs ADR-0020, ADR-0028
Traces: requirements FR-09, FR-11
Depends on AIFACTORY-US-284, AIFACTORY-US-285, AIFACTORY-US-286, AIFACTORY-US-289, feature:component-saas-metering-template
Sources model/components.yaml, model/services/control-plane/CostUsageService.yaml, docs/architecture/ecosystem-composition.md, docs/architecture/adr/0020-commercial-model.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-1283 Acceptance fixture that generates and hosts the Metering service of the published template fixture The acceptance suite of CostUsageService installs the published template package, generates a Metering service with UseFactoryProfile, configures it with the seven allowed dimensions, hosts it with its store in the acceptance environment and can stop and start it; the suite holds the double export, the outage, the clean window, the late record and the planted difference cases against it. ConnectSoft.AI.SoftwareFactory.CostUsageService
AIFACTORY-TASK-1284 Verify export and reconciliation against the generated Metering service verification Run the acceptance suite of CostUsageService against the Metering service generated from the published template package; the double export, outage, clean window, late record and planted difference cases pass with no stub between the services and prove AC1 to AC3 of AIFACTORY-US-287 (FR-09, FR-11, ADR-0020). ConnectSoft.AI.SoftwareFactory.CostUsageService

AIFACTORY-US-088: Factory usage is metered in the metering service and reconciled

behavior · persona operator As an operator, I want every settled usage record of the Factory exported to the metering service in its units and reconciled against it, so that what a tenant is billed for equals what the Factory observed.

This is the integration PBI of the feature. With the published typed client, the meter map, the Metering service of the Factory in its own repository and deployable, the export worker, the meter reconciliation and the proof against a generated Metering service of the earlier PBIs, the usage of the Factory has one measurement. A usage record that CostUsageService settles, announced by CostUsageService/UsageRecorded or confirmed by CostUsageService/UsageReconciled, is written to the Metering service once, in the dimension and the unit of its meter, under the tenant and in the window the Metering service reports for it, which the export row stores, with the usage identifier as its idempotency key. A repeated export adds nothing. While the Metering service cannot be reached the record waits as pending and nothing is marked exported. When a window closes, the usage of the Factory and the usage of the Metering service are compared, every difference is listed with the identifiers of its records, a record that was counted in a later window than its time of occurrence is listed as late, and a window without a difference is marked reconciled; nothing is repaired by the comparison. An operator sees pending exports and differing windows through the metrics and the log of the service. The implementation lives in the tasks of the earlier PBIs; this PBI keeps the migrated verification of the feature and the entry of the two workers in the model of the service. The feature is done when the acceptance suite passes against a Metering service generated from the published template package and the Factory instance of AIFACTORY-US-290 is deployed and ready with the seven dimensions, so that what a tenant is billed for equals what the Factory observed.

Acceptance criteria

AC1 Given a settled usage record in CostUsageService, announced by CostUsageService/UsageRecorded, when the export runs, then one metered usage record exists in the metering service with the same quantity in its unit, the same tenant and the window the Metering service reports for it, stored on the export row, and a repeated export creates no duplicate (ADR-0020 decision 2, ADR-0014 decision 3).
AC2 Given the usage of the Factory and the usage of the metering service for a closed window, when the meter reconciliation runs, then every difference is listed with its record identifiers, a late record is listed without counting as a difference, and a window with no difference is marked reconciled (FR-09, ADR-0020 decision 3).
AC3 Given the metering service is unreachable, when the export runs, then the records stay pending, the export retries with backoff and nothing is marked exported (ADR-0020 decision 3, model/services/control-plane/CostUsageService.yaml).
Traces: services CostUsageService
Traces: aggregates CostUsageService/UsageRecord
Traces: events CostUsageService/UsageRecorded, CostUsageService/UsageReconciled
Traces: adrs ADR-0020, ADR-0014
Traces: requirements FR-09
Depends on AIFACTORY-US-284, AIFACTORY-US-285, AIFACTORY-US-286, AIFACTORY-US-287, AIFACTORY-US-289, AIFACTORY-US-290, feature:cost-usage-service-complete
Sources model/components.yaml, model/services/control-plane/CostUsageService.yaml, docs/architecture/ecosystem-composition.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-1285 Model of CostUsageService names the export and the meter reconciliation documentation model/services/control-plane/CostUsageService.yaml names the export worker and the meter reconciliation worker with their triggers, retry policies and idempotency keys, the export and reconciliation result tables and the dependency on the typed client of the Metering service; the read operation for the reconciliation result, which the model lacks, is not invented by this task and stays a reported gap; the generated pages of the service are regenerated and python -I tools/docs_model check passes. ConnectSoft.AI.SoftwareFactory.Documentation
AIFACTORY-TASK-690 Verify usage-metered-and-reconciled by running the declared command verification Run dotnet test -c Release --filter Category=Acceptance against the Metering service generated from the published template package; a zero-match filter counts as a failure; it passes and proves AC1 to AC3 of AIFACTORY-US-088. ConnectSoft.AI.SoftwareFactory.CostUsageService