AIFACTORY-FEAT-090: Contracts package from the published schemas¶
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 Engineering readiness · Increment I0 Readiness · State elaborated · Route backend-developer · Build order 1 of 185 (Templates and libraries)
The run envelope, the topic names, the descriptors and the JSON schemas of this repository are published as one versioned contracts package, so that two services never copy a contract.
| Delivers | — |
| Stubs | — |
| Realizes | adrs: ADR-0014 |
| Requirements | — |
| Depends on | — |
| Sources | docs/architecture/capability-dependencies.md, docs/ai-software-factory/current-state.md |
AIFACTORY-US-366: Contracts package: the contract types are generated at build from the published JSON schemas of this repository and stamped with the hash of each schema¶
enabling · persona platform-admin
As a platform admin, I want every contract type of the Factory to be generated from the schema file this repository publishes, so that two services never copy a contract and a schema change cannot pass unnoticed.
The feature publishes the run envelope, the topic names, the descriptors and the JSON schemas of this repository as one versioned package, so that two services never copy a contract. This PBI delivers the types. The repository ConnectSoft.AI.SoftwareFactory.Contracts is scaffolded from the library template with the Factory scaffold command, dotnet new connectsoft-library -n ConnectSoft.AI.SoftwareFactory.Contracts --UseFactoryProfile true; the feature component-library-template-factory-profile delivers that profile, the generation manifest and the generated pipeline, and this PBI depends on it. The source of every type is a schema file under docs/reference/schemas that model/descriptors.yaml registers under a descriptor id. How the files reach the Contracts repository is stated and not assumed: an intake folder of that repository holds a copy of each schema file and one JSON document of the events of the service files, an intake file records the revision of this repository they were taken from and the content hash of each schema file and of the event list, and one documented command refreshes the intake from a checkout of this repository, so that a .NET build reads only files of its own repository. The package embeds the schema files of the intake and generates at build one contract type per descriptor whose schema file defines its shape: the run submission, the run event envelope, the approval request and decision, the artifact, the blueprint version reference, the readiness bundle, the execution scope, the attempt outcome, the policy decision, the tool and model invocations with their receipts, the usage record and the blueprint descriptors. No type is written by hand. Seven descriptors are registered on a schema file that does not define their shape and are not generated: run-accepted-v1 and run-ref-v1 on the file of the run submission, which has one object, run-view-v1 and run-list-v1 on the file of the resolved execution snapshot, run-event-v1 on the file of the envelope, and approval-ref-v1 and approval-list-v1 on the approval file, which defines the request and the decision only. The package lists them as not generated. Whether their definitions are added to the schema files or they stay out of the first package version is an open question for the owner, and this PBI decides neither shape. The approval file is also behind the model: its state enumeration lacks ChangesRequested (decision D113) and the request lacks onExpiry and reRequestsLeft (decision D115) while it admits no additional property, so a generated type would refuse a valid approval. A documentation task in this repository brings the file up to the model before the first version of the package is published, so no published descriptor version changes. A stamp in the package records, per descriptor, the schema file and its content hash. A test fails when a schema file of the intake differs from its stamp while the package version is unchanged, and a stage of the pipeline refreshes the intake from a checkout of this repository and fails when a refreshed hash differs from the stamp under an unchanged package version, which is what notices that this repository moved on. Required and optional follow the schema: run-submission-v1 has an optional environmentId (decision D114), so the generated type carries it as an optional member and a run submitted without it is never gated by an environment. Decision D117 adds three such cases, and the types follow the schema files in each. The usage record of usage-record-v1 meters model tokens as two meters, model.input-tokens and model.output-tokens, each with a price of its own, and requires neither quantity nor runId nor pricingRevision, so a record with the status uncertain is built without a quantity and without a run and is priced or reconciled later. The approval request of approval-request-v1 leaves stepId, leaseId and fencingToken optional, so a run-level spend approval, which gates no step, is built without them. A document that validates against its schema deserialises into its type and serialises back to an equivalent document, and a document that misses a required field is refused with the field named. Versioning follows ADR-0014 decision 6: a new field arrives in a new version, and a change that removes or renames a field or adds a required one under an existing descriptor version fails the compatibility test, because it needs a descriptor version of its own. The package references no service, no transport and no host; a consumer pins it and validates at run time against the very schema file the type was generated from.
Acceptance criteria
| AC1 | Given the schema files that model/descriptors.yaml registers, when the package builds, then one contract type exists for each descriptor whose schema file defines its shape, the run submission, the run event envelope, the approval request and decision, the artifact, the blueprint version reference and the readiness bundle among them, each generated from its schema file and none written by hand; the stamp of the package records the schema file and its content hash per descriptor; and run-accepted-v1, run-ref-v1, run-view-v1, run-list-v1, run-event-v1, approval-ref-v1 and approval-list-v1, for which the schema file they are registered on defines no shape, are listed by the package as not generated (ADR-0014; docs/reference/schemas/index.md). |
| AC2 | Given the descriptor run-submission-v1, when its type is generated, then environmentId is an optional member: a submission without it serialises without the member and validates against docs/reference/schemas/run-submission.schema.json, and a submission with it round-trips unchanged. |
| AC3 | Given one stored sample document per descriptor whose schema file defines its shape, when it is deserialised into its generated type and serialised again, then the result validates against the embedded schema file and equals the sample, and a document that misses a required field is refused with the field named (descriptors run-submission-v1, approval-request-v1, artifact-v1, blueprint-version-ref-v1 and readiness-bundle-v1 are among the samples); a usage record of usage-record-v1 with the status uncertain and without quantity, runId and pricingRevision round-trips, and its meter admits model.input-tokens and model.output-tokens as two meters, as docs/reference/schemas/usage-record.schema.json states them. |
| AC4 | Given a schema file of the intake whose content hash differs from the stamp of the package, when the tests run under an unchanged package version, then the stamp test fails with the descriptor named; given the intake refreshed from a checkout of this repository, when a refreshed hash of a schema file or of the event list differs from the stamp under an unchanged package version, then the pipeline fails; and given a change that removes or renames a field or adds a required one under an existing descriptor version, then the compatibility test fails, because ADR-0014 decision 6 admits new fields only in a new version. |
| AC5 | Given docs/reference/schemas/approval.schema.json after the documentation task, when the approval types are generated, then the state of the request admits ChangesRequested and the request carries onExpiry and reRequestsLeft as model/services/control-plane/RunControlService.yaml states them, a sample approval in the state ChangesRequested round-trips, a run-level spend approval without stepId, leaseId and fencingToken round-trips, and python -I tools/docs_model check passes (descriptor approval-request-v1). |
| Traces: descriptors | run-submission-v1, run-event-envelope-v1, approval-request-v1, artifact-v1, blueprint-version-ref-v1, readiness-bundle-v1, execution-scope-v1, usage-record-v1 |
| Traces: adrs | ADR-0014, ADR-0028 |
| Depends on | feature:component-library-template-factory-profile |
| Sources | docs/architecture/adr/0014-run-and-lifecycle-envelopes.md, docs/architecture/capability-dependencies.md, docs/ai-software-factory/current-state.md, docs/reference/schemas/index.md, docs/reference/schemas/run-submission.schema.json, docs/reference/schemas/approval.schema.json, docs/reference/schemas/usage-record.schema.json, model/descriptors.yaml |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1522 Scaffold the contracts repository from the library template with the Factory profile |
implementation | The repository ConnectSoft.AI.SoftwareFactory.Contracts holds the unchanged output of dotnet new connectsoft-library -n ConnectSoft.AI.SoftwareFactory.Contracts --UseFactoryProfile true with the template package restored from the ConnectSoft feed; the solution builds, its template tests pass, the generation manifest records the template version and the parameter values, and the generated pipeline names the ConnectSoft feed. |
ConnectSoft.AI.SoftwareFactory.Contracts |
AIFACTORY-TASK-144 Generate contract types from docs/reference/schemas |
implementation | A package with one type per descriptor whose schema file defines its shape, the run submission with its optional environmentId, the envelope, the approval request and decision with the optional step of a run-level spend approval, the usage record with its two token meters and its optional quantity and run, the artifact, the blueprint version reference and the readiness bundle among them, generated at build from the schema files of the intake of AIFACTORY-TASK-1567, embedded in the package and stamped per descriptor with the schema file and its content hash; the seven descriptors whose schema file defines no shape for them are listed as not generated. |
ConnectSoft.AI.SoftwareFactory.Contracts |
AIFACTORY-TASK-1567 Intake of the schema files and the event list from this repository with a recorded revision and hashes |
contract | An intake folder of the Contracts repository holds a copy of each schema file under docs/reference/schemas and one JSON document of the integration events of the service files under model/services (service, event name, topic, version, payload fields with type and required flag, and the enums of each service); an intake file records the source revision of this repository and the content hash of each schema file and of the event list; one documented command refreshes the intake from a checkout of this repository; a stage of the pipeline runs the refresh and fails when a refreshed hash differs from the stamp under an unchanged package version. |
ConnectSoft.AI.SoftwareFactory.Contracts |
AIFACTORY-TASK-1568 ChangesRequested, onExpiry and reRequestsLeft in the approval schema file |
documentation | docs/reference/schemas/approval.schema.json admits ChangesRequested in the state enumeration of the approval request and declares onExpiry and reRequestsLeft on the request, as model/services/control-plane/RunControlService.yaml states them (decisions D113 and D115); the change is made before the first version of the contracts package is published, docs/reference/schemas/index.md names it, and python -I tools/docs_model check passes, which proves the schema half of AC5 of AIFACTORY-US-366. |
ConnectSoft.AI.SoftwareFactory.Documentation |
AIFACTORY-TASK-1523 Verify the generated types, the stamp and the compatibility test |
verification | Run dotnet test -c Release --no-build on the contracts solution; the round trip of one sample per generated descriptor, the list of the seven descriptors that are not generated, the optional environmentId of run-submission-v1, the approval in the state ChangesRequested with onExpiry and reRequestsLeft, the run-level spend approval without a step, the uncertain usage record without a quantity and a run with its two token meters, the refusal of a missing required field, the stamp test on a planted changed schema, the intake stage on a planted changed hash and the compatibility test on a planted removed field pass and prove AC1 to AC5 of AIFACTORY-US-366 (ADR-0014). |
ConnectSoft.AI.SoftwareFactory.Contracts |
AIFACTORY-US-367: Contracts package: the run event envelope, the topic constants and the event types are generated from the model, with the optional failure class of AttemptOutcomeReported¶
enabling · persona platform-admin
As a platform admin, I want the envelope, the topic names and the event types of the Factory to exist once, generated from the model, so that a publisher and a consumer in two repositories cannot disagree on a topic, a field or a version.
ADR-0014 decision 1 makes event id, schema version, occurred-at, the trusted tenant id, project id, run id, step id and attempt id where applicable, correlation id, producer identity and event type the required fields of the port-level envelope, with the causation id optional since the amendment of the ADR on the causation id (decision D117), and keeps the trace id as diagnostic correlation that is never an authorization or idempotency key. Its amendment on envelopes per event family (decision D114) settles who writes which envelope: a Factory service writes the run event envelope of this package for its integration events, and AgentEventEnvelope of the Factory messaging library carries agent lifecycle events only, with the same scope fields. This PBI delivers that envelope and what travels in it. The envelope type is generated from docs/reference/schemas/run-event-envelope.schema.json and cannot be built without the fields the schema requires, the tenant among them; the project, run, step and attempt are optional members, the classification defaults to internal, and the topic follows the pattern of the schema. The causation id is optional: the first event of a chain has none, the schema leaves causationId optional and the amendment of ADR-0014 on the causation id says the same, so the type carries it as an optional member. For every integration event that a service file under model/services declares, a generator writes the event type name, the topic constant, the version and a payload record with the fields the model lists; a field the model marks as not required is an optional member. The generator reads the event list of the intake that AIFACTORY-US-366 delivers and maps each field by its model type: string to a string, guid to a GUID, int and long to integers of that width, bool, decimal, datetime to a UTC instant, hash to a string that holds the hash text, json to a raw JSON element, list:string to a read-only list of strings, and enum:<Name> to an enum type generated from the enums of the service file that declares the event. AttemptOutcomeReported of AgentRuntimeService is the case decision D114 names: its payload carries an optional failureClass, present on a failed attempt as ADR-0014 decision 2 requires and absent otherwise. No service types a topic or an event type name of its own; it references the constant. A test compares the generated constants and records with the event list of the intake, and the pipeline stage that refreshes the intake from a checkout of this repository fails when an event, a topic, a version or a payload field of the model changed while the package version did not. The event records implement the event contract of the messaging port, IEvent of ConnectSoft.Extensions.MessagingModel, so that a service publishes them through the port; that contracts package is the one dependency ADR-0012 decision 1 allows event types. The package declares no agent lifecycle event and no AgentEventEnvelope and references no adapter, no transport and not the Factory messaging library; the serialised names of the scope fields are the ones the contract test of the messaging library compares its own envelope with.
Acceptance criteria
| AC1 | Given the package, when a service builds an envelope for an integration event, then event id, event type, schema version, occurred-at, producer, tenant id, correlation id and payload must be supplied, an envelope without a tenant cannot be built, project, run, step and attempt are optional members, causationId is an optional member, as the schema and the amendment of ADR-0014 on the causation id state, because the first event of a chain has none, the trace id is a diagnostic member only, and the serialised envelope validates against docs/reference/schemas/run-event-envelope.schema.json (ADR-0014 decision 1, descriptor run-event-envelope-v1). |
| AC2 | Given the integration events that the service files under model/services declare, when the package is generated, then each event has an event type name, a topic constant equal to the topic of the model, its version and a payload record with the fields of the model, an enum: field is an enum type generated from the enums of the service file, and the intake stage of the pipeline fails when an event, a topic, a version or a payload field of the model changed without a new package version (ADR-0014 decision 6; model/services/control-plane/RunControlService.yaml is one of the files read). |
| AC3 | Given the payload of AttemptOutcomeReported as model/services/agent-mesh/AgentRuntimeService.yaml states it, when its record is generated, then failureClass is an optional member: the outcome of a completed attempt serialises without it and the outcome of a failed attempt carries it, as ADR-0014 decision 2 and its amendment on the failure class of a failed attempt require. |
| AC4 | Given the package assembly, when its architecture test runs, then its event records implement the event contract of ConnectSoft.Extensions.MessagingModel and that contracts package is the only messaging reference; the assembly references no adapter, no transport and no ConnectSoft.Extensions.AI.Factory.Messaging, and declares no agent lifecycle event and no AgentEventEnvelope, because that envelope carries agent lifecycle events only and a Factory service writes the envelope of this package (ADR-0014 amendment on envelopes per event family, ADR-0012 decision 1). |
| Traces: descriptors | run-event-envelope-v1 |
| Traces: adrs | ADR-0012, ADR-0014 |
| Depends on | AIFACTORY-US-366 |
| Sources | docs/architecture/adr/0014-run-and-lifecycle-envelopes.md, docs/architecture/adr/0012-messaging-port-and-transport-profiles.md, docs/reference/event-envelope.md, docs/reference/schemas/run-event-envelope.schema.json, model/services/agent-mesh/AgentRuntimeService.yaml, model/services/control-plane/RunControlService.yaml |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-145 Topic and envelope constants |
implementation | Topic names, event type names and envelope fields as constants generated from the event list of the intake of AIFACTORY-TASK-1567, which is taken from the service files under model/services at the recorded revision of this repository, with a test that compares the constants with that list and the intake stage that fails when an event, a topic, a version or a payload field of the model changes without a package version. | ConnectSoft.AI.SoftwareFactory.Contracts |
AIFACTORY-TASK-1524 Run event envelope type and payload records of the integration events |
contract | The package holds the run event envelope type generated from docs/reference/schemas/run-event-envelope.schema.json, which cannot be built without the required fields and carries causationId as an optional member, and one payload record per integration event of the model with a member per payload field, optional where the model marks the field as not required; the type mapping is string to a string, guid to a GUID, int and long to integers of that width, bool, decimal, datetime to a UTC instant, hash to a string that holds the hash text, json to a raw JSON element and list:string to a read-only list of strings, and an enum: field is generated as an enum type from the enums of the service file; the records implement the event contract of ConnectSoft.Extensions.MessagingModel; the record of AttemptOutcomeReported carries the optional failureClass; the package declares no AgentEventEnvelope and no agent lifecycle event. |
ConnectSoft.AI.SoftwareFactory.Contracts |
AIFACTORY-TASK-1525 Verify the envelope, the generated event types and the model comparison |
verification | Run dotnet test -c Release --no-build on the contracts solution; the envelope validation against run-event-envelope-v1, the refusal of an envelope without a tenant, the optional causationId, the comparison of every topic and payload with the event list of the intake, the enum types, the optional failureClass and the architecture test pass and prove AC1 to AC4 of AIFACTORY-US-367 (ADR-0014). |
ConnectSoft.AI.SoftwareFactory.Contracts |
AIFACTORY-US-368: Contracts package: the audit evidence event type AuditEvidenceSubmitted, the topic constant audit.evidence.v1.evidence-submitted and a submission shape without the chain hash¶
enabling · persona platform-admin
As a platform admin, I want the evidence event that every service submits to be declared once in the contracts package, in the shape a service can submit, so that every Factory service records audit evidence the same way and none computes a chain hash it cannot know.
Audit evidence travels as an event (decision D115): a service writes it to its outbox in the transaction of its command, and the Audit service has the command SubmitEvidence for it on the topic audit.evidence.v1.evidence-submitted, appending once per evidence identifier by the same append as Audit.Record, which stays for commands that are not events. Every service publishes that event, so it is no event of one producer in the model and the generator of AIFACTORY-US-367 does not find it in a list of events. This PBI declares it once, by hand, in the contracts package: the evidence event type, named AuditEvidenceSubmitted (decision D117), the topic constant, and the shape of what a service submits. That shape is the record of the descriptor audit-evidence-v1 without chainHash. The chain hash is computed by the Audit service when it appends the record, because only that service knows the previous record of the tenant; a service never submits it. The schema file does not allow this today: docs/reference/schemas/audit-evidence.schema.json marks chainHash as required and admits no additional property, so a submitted record cannot validate against it. Decision D117 settles how: the submission shape is a second definition under the descriptor audit-evidence-v1. A documentation task in this repository therefore adds that definition to the schema file, so that it describes two shapes under the same descriptor: the submitted record, in which chainHash is not admitted, and the stored record of the Audit service, in which it stays required. The package generates both from the changed file. The payload of the evidence event is the submission shape only; the stored record is what the Audit service keeps and returns. The closed list of actions, the actor kinds and the correlation with run, approval and event identifiers are those of the schema and are not widened here. The Audit library of the feature component-audit-factory-evidence pins this package for the record its builder returns and for the event type and the topic its sink publishes on, and declares none of them.
Acceptance criteria
| AC1 | Given the package, when a consumer references the evidence event, then its event type name AuditEvidenceSubmitted and the topic constant audit.evidence.v1.evidence-submitted are constants of the package, and a test asserts that the constant equals the topic that model/services/governance/AuditService.yaml names for the command SubmitEvidence (descriptor audit-evidence-v1). |
| AC2 | Given the submission shape of the package, when a service builds an evidence record, then the record holds every field of audit-evidence-v1 except chainHash, a record without evidence identifier, tenant, time, actor, action, subject or outcome cannot be built, and a serialised submission that carries a chainHash member is refused by the validation against the submitted record of docs/reference/schemas/audit-evidence.schema.json. |
| AC3 | Given docs/reference/schemas/audit-evidence.schema.json after the documentation task, when it is read, then it describes the submitted record, in which chainHash is not admitted, beside the stored record, in which chainHash stays required, docs/reference/schemas/index.md names both shapes under the descriptor audit-evidence-v1, and python -I tools/docs_model check passes. |
| AC4 | Given the evidence event of the package, when it is wrapped as the payload of run-event-envelope-v1, then the payload type is the submission shape only, the stored record with its required chainHash cannot be used as the payload of the event, and the serialised event validates against both schema files (ADR-0014 decision 4 is the reason the evidence travels as an outbox event). |
| Traces: descriptors | audit-evidence-v1, run-event-envelope-v1 |
| Traces: adrs | ADR-0014 |
| Depends on | AIFACTORY-US-366, AIFACTORY-US-367 |
| Sources | docs/reference/schemas/audit-evidence.schema.json, docs/reference/schemas/index.md, docs/architecture/adr/0014-run-and-lifecycle-envelopes.md, model/services/governance/AuditService.yaml, model/descriptors.yaml |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1526 Submitted and stored record in the audit evidence schema file |
documentation | docs/reference/schemas/audit-evidence.schema.json describes two shapes as two definitions under the descriptor audit-evidence-v1: the submitted record, which holds every field except chainHash and does not admit it, and the stored record of the Audit service, in which chainHash stays required; docs/reference/schemas/index.md names both and states that the Audit service computes the chain hash when it appends the record; python -I tools/docs_model check passes with the changed file, which proves AC3 of AIFACTORY-US-368. |
ConnectSoft.AI.SoftwareFactory.Documentation |
AIFACTORY-TASK-1527 Evidence event type, topic constant and submission shape in the contracts package |
contract | The package declares the evidence event type AuditEvidenceSubmitted, the topic constant audit.evidence.v1.evidence-submitted and the submission record generated from the submitted shape of the schema file, beside the stored record with its required chainHash; the payload type of the evidence event is the submission record, and a test compares the topic constant with model/services/governance/AuditService.yaml. |
ConnectSoft.AI.SoftwareFactory.Contracts |
AIFACTORY-TASK-1528 Verify the evidence event and the two record shapes |
verification | Run dotnet test -c Release --no-build on the contracts solution; the topic comparison, the build of a submission without chainHash, the refusal of a submission that carries it, the stored record with its required hash and the envelope with the evidence payload pass and prove AC1, AC2 and AC4 of AIFACTORY-US-368; AC3 is proven by AIFACTORY-TASK-1526 in the documentation repository (descriptor audit-evidence-v1). |
ConnectSoft.AI.SoftwareFactory.Contracts |
AIFACTORY-US-369: Contracts package: the package is built, tested and published to the ConnectSoft feed with a version its consumers pin, and a probe consumer restores it from the feed alone¶
evidence · persona platform-admin
As a platform admin, I want proof that the contracts package is on the ConnectSoft feed with a version a consumer can pin, so that the templates and the services restore one definition of every contract and never a local copy.
This PBI is the publication proof of the feature. The base template profile, the Audit library, the observability libraries, the API library template and, later, every Factory service pin the contracts package, so it has to be on the feed before any of them is built. The feed is the ConnectSoft feed, the Azure Artifacts feed the ConnectSoft libraries already publish to (decision D114); no second feed is created. The pipeline of the contracts repository is the one the library template generates: it builds, tests, packs the library with its symbols and publishes it with a version that is verified against the feed before the push, and a version that is already on the feed is refused with the reason. That generated pipeline runs unchanged: the repository adds only the probe stage and the intake stage, holds no pack or push script of its own, and reports a gap of the generated pipeline to the template feature. A publication is reached only after the tests of the solution pass, and those tests are the gates of the earlier PBIs: the stamp test over the schema files, the comparison of the generated topics and payloads with the model, the compatibility test and the architecture test. A probe then proves the result from the side of a consumer. A clean project that has the ConnectSoft feed as its only source and no project reference restores the published version and builds; it builds a run submission with and without environmentId, a run event envelope, a payload of AttemptOutcomeReported with and without failureClass and an evidence submission, validates each against the schema file embedded in the package, and reads the topic constant of the evidence event. The published version is recorded on the reference page of the schemas on this site, which is where a consuming template or service reads its pin. The demonstration of increment I0 that two services consume the package is carried by the feature that verifies the increment; the probe and the recorded version are what it builds on.
Acceptance criteria
| AC1 | Given the pipeline of the contracts repository, when it runs after the work of the feature, then the package is built, tested, packed and pushed to the ConnectSoft feed with a version that was not on the feed, the publication stage runs only after the tests of the solution pass, and the published version is recorded on docs/reference/schemas/index.md (ADR-0028 amendment on the Factory profile switch names the feed). |
| AC2 | Given a clean consumer project with the ConnectSoft feed as its only package source and no project reference, when it restores the published version and builds, then it builds a run submission, an envelope of run-event-envelope-v1, a payload of AttemptOutcomeReported and an evidence submission, each validates against the schema file embedded in the package, and the topic constant of the evidence event reads audit.evidence.v1.evidence-submitted (ADR-0014 decision 1). |
| AC3 | Given a planted schema file that differs from its stamp, or a version that is already on the feed, when the pipeline reaches the publication stage, then the stage is refused with the reason and nothing is pushed; a run with the planted file proves the refusal (ADR-0014 decision 6; docs/reference/schemas/index.md keeps the earlier version). |
| Traces: descriptors | run-event-envelope-v1 |
| Traces: adrs | ADR-0014, ADR-0028 |
| Depends on | AIFACTORY-US-366, AIFACTORY-US-367, AIFACTORY-US-368, feature:component-library-template-factory-profile |
| Sources | docs/architecture/adr/0014-run-and-lifecycle-envelopes.md, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, docs/reference/schemas/index.md, model/backlog/increments.yaml |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1529 First publishing run of the generated pipeline of the contracts repository |
operations | The pipeline that the library template generated for the contracts repository runs unchanged: one green run publishes the package and its symbols to the ConnectSoft feed after the tests of the solution pass, and one run with a repeated version is refused with the reason; the repository adds only the probe stage of AIFACTORY-TASK-1530 and the intake stage of AIFACTORY-TASK-1567; a gap found in the generated pipeline is reported to feature component-library-template-factory-profile and not patched in the repository. |
ConnectSoft.AI.SoftwareFactory.Contracts |
AIFACTORY-TASK-1530 Feed probe consumer for the published contracts package |
fixture | A probe project with the ConnectSoft feed as its only source and no project reference restores the published version, builds a run submission with and without environmentId, an envelope, a payload of AttemptOutcomeReported with and without failureClass and an evidence submission, validates each against the embedded schema file and reads the topic constant of the evidence event; the probe runs as the last stage of the pipeline. |
ConnectSoft.AI.SoftwareFactory.Contracts |
AIFACTORY-TASK-1531 Published version of the contracts package recorded on the schemas reference page |
documentation | docs/reference/schemas/index.md names the published version of the contracts package, the revision of this repository its schema files and events were taken from and the descriptors it holds, and states that a Factory service writes the run event envelope of this package for its integration events while AgentEventEnvelope carries agent lifecycle events only. |
ConnectSoft.AI.SoftwareFactory.Documentation |
AIFACTORY-TASK-1532 Verify the published package by the probe and by a planted failing run |
verification | One run of the pipeline publishes the package and the probe passes; one run with a planted schema file that differs from its stamp stops before publication and pushes nothing; both runs prove AC1 to AC3 of AIFACTORY-US-369 (ADR-0014, ADR-0028). | ConnectSoft.AI.SoftwareFactory.Contracts |
AIFACTORY-US-095: Contracts package from the published schemas is delivered and proven by its consumers¶
enabling · persona platform-admin
As a platform admin, I want contracts package from the published schemas, so that every Factory service reads the envelope, topics, descriptors and schemas from one versioned package.
This is the integration PBI of the feature. A platform admin takes the schemas and the events of this repository to one published package: the contract types generated from the schema files with a stamp per descriptor (AIFACTORY-US-366), the run event envelope with the topic constants and the event types generated from the model (AIFACTORY-US-367), the audit evidence event AuditEvidenceSubmitted with its topic constant and a submission shape without the chain hash (AIFACTORY-US-368), and the publication to the ConnectSoft feed with a probe consumer (AIFACTORY-US-369). The implementation lives in those PBIs; this one proves them together from the side of the consumers. The decisions the package carries are the ones the model and the amendments of ADR-0014 state: a Factory service writes the run event envelope of this package for its integration events, while AgentEventEnvelope of the Factory messaging library carries agent lifecycle events only; run-submission-v1 has an optional environmentId; AttemptOutcomeReported carries an optional failureClass; the Audit service computes the chain hash, so the submitted evidence record has none. Decision D117 adds to them: the causation id of the envelope is optional, the usage record meters model tokens as two meters, input tokens and output tokens, and admits an uncertain record without a quantity and without a run, and an approval request admits a run-level spend approval without a step. The feature is done when the package is on the feed with a recorded version, a consumer that has only the feed builds every contract and validates it against the embedded schema, and a change of a schema file or of an event of the model cannot be published without a new version. Repository of the feature: ConnectSoft.AI.SoftwareFactory.Contracts; the schema changes of the audit evidence record and of the approval request and the recorded version are documentation tasks in this repository.
Acceptance criteria
| AC1 | Given the library repository ConnectSoft.AI.SoftwareFactory.Contracts, when its pipeline runs, then the package builds, its tests pass and it publishes to the ConnectSoft feed with a verified version that the consuming repositories pin (ADR-0028; docs/reference/schemas/index.md records the version). |
| AC2 | Given the work of AIFACTORY-TASK-144 (generate contract types from docs/reference/schemas) is done, then the package holds one type per descriptor of model/descriptors.yaml whose schema file defines its shape, the run submission, envelope, approval, artifact, blueprint reference and readiness bundle among them, generated and version-stamped from the schema files (ADR-0014). |
| AC3 | Given the work of AIFACTORY-TASK-145 (topic and envelope constants) is done, then topic names, event type names and envelope fields exist as constants generated from the model, with a test that fails when the model changes without a package version, and the payload of AttemptOutcomeReported carries its optional failureClass (ADR-0014 decision 2; model/services/agent-mesh/AgentRuntimeService.yaml). |
| AC4 | Given the published package, when a service submits audit evidence, then it uses the evidence event type AuditEvidenceSubmitted, the topic constant audit.evidence.v1.evidence-submitted and the submission shape of audit-evidence-v1 without chainHash from the package, and the schema file docs/reference/schemas/audit-evidence.schema.json describes that shape beside the stored record. |
| AC5 | Given a Factory service that publishes an integration event, when it pins the package, then it writes the envelope run-event-envelope-v1 of the package, and the package offers no AgentEventEnvelope, which stays the envelope of agent lifecycle events in the Factory messaging library (ADR-0014 amendment on envelopes per event family). |
| Traces: descriptors | run-event-envelope-v1, audit-evidence-v1 |
| Traces: adrs | ADR-0014, ADR-0028 |
| Depends on | AIFACTORY-US-366, AIFACTORY-US-367, AIFACTORY-US-368, AIFACTORY-US-369 |
| Sources | docs/architecture/capability-dependencies.md, docs/ai-software-factory/current-state.md, docs/architecture/adr/0014-run-and-lifecycle-envelopes.md, docs/reference/schemas/index.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1533 Build every contract of the published package from a consumer that has only the feed |
verification | A consumer test project restores the published package from the ConnectSoft feed and is exhaustive where the feed probe of AIFACTORY-TASK-1530 is a smoke over five documents: for every descriptor the package generates it builds a document, validates it against the embedded schema file and compares its stamp with the pinned intake, and for every event type of the package it builds one envelope and compares the topic constant and the payload members with the event list of the intake, which proves AC2 to AC5 of AIFACTORY-US-095. | ConnectSoft.AI.SoftwareFactory.Contracts |
AIFACTORY-TASK-713 Verify contracts-package-delivered by running the declared command |
verification | Run dotnet build -c Release and dotnet test -c Release --no-build; they pass and prove AC1 to AC5 of AIFACTORY-US-095. |
ConnectSoft.AI.SoftwareFactory.Contracts |