@agent-ix/spec-artifacts-app 0.4.1 → 0.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +40 -1
- package/manifest.yaml +276 -4
- package/mappings.schema.json +318 -0
- package/mappings.yaml +386 -0
- package/package.json +10 -2
- package/schemas/Actor.json +34 -0
- package/schemas/ActorId.json +7 -0
- package/schemas/ActorKind.json +13 -0
- package/schemas/ApplicationSpec.json +116 -0
- package/schemas/ArtifactId.json +7 -0
- package/schemas/ArtifactStatus.json +7 -0
- package/schemas/Boundary.json +34 -0
- package/schemas/BoundaryId.json +7 -0
- package/schemas/BoundaryKind.json +12 -0
- package/schemas/Capability.json +37 -0
- package/schemas/CapabilityId.json +7 -0
- package/schemas/Cardinality.json +7 -0
- package/schemas/DataAccessMode.json +11 -0
- package/schemas/DataDependency.json +33 -0
- package/schemas/DataDependencyId.json +7 -0
- package/schemas/EdgeVerb.json +7 -0
- package/schemas/ImportedTypeRef.json +21 -0
- package/schemas/Interface.json +38 -0
- package/schemas/InterfaceDirection.json +11 -0
- package/schemas/InterfaceId.json +7 -0
- package/schemas/InterfaceKind.json +15 -0
- package/schemas/IxTarget.json +7 -0
- package/schemas/LineNumber.json +8 -0
- package/schemas/MasterRequirements.json +80 -0
- package/schemas/ModuleRef.json +7 -0
- package/schemas/NonEmptyText.json +7 -0
- package/schemas/Provenance.json +25 -0
- package/schemas/Relationship.json +24 -0
- package/schemas/RenderingRequirement.json +34 -0
- package/schemas/RenderingRequirementId.json +7 -0
- package/schemas/RequirementKind.json +14 -0
- package/schemas/RequirementRef.json +33 -0
- package/schemas/RequirementRefId.json +7 -0
- package/schemas/Section.json +26 -0
- package/schemas/Sha256Digest.json +7 -0
- package/schemas/TestCaseRef.json +7 -0
- package/schemas/TypeName.json +7 -0
- package/schemas/UiSurface.json +7 -0
- package/schemas/Verification.json +29 -0
- package/schemas/toolchain.json +65 -0
- package/skeletons/application-spec.md +163 -0
- package/skeletons/application-spec.sysml.md +167 -0
- package/skeletons/master-requirements.md +104 -0
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
{
|
|
2
|
+
"compiler": {
|
|
3
|
+
"name": "@typespec/compiler",
|
|
4
|
+
"version": "1.15.0"
|
|
5
|
+
},
|
|
6
|
+
"emitter": {
|
|
7
|
+
"name": "@typespec/json-schema",
|
|
8
|
+
"version": "1.15.0"
|
|
9
|
+
},
|
|
10
|
+
"semanticCore": {
|
|
11
|
+
"name": "@agent-ix/semantic-core",
|
|
12
|
+
"version": "0.3.0"
|
|
13
|
+
},
|
|
14
|
+
"base": "https://schemas.agent-ix.org/agent-ix/spec-artifacts-app/0.2.0/",
|
|
15
|
+
"normalization": {
|
|
16
|
+
"name": "absolute-id-and-ref",
|
|
17
|
+
"version": "1.0.0",
|
|
18
|
+
"issue": "https://github.com/agent-ix/spec-artifacts-app/issues/3",
|
|
19
|
+
"applied": false,
|
|
20
|
+
"rewrittenFiles": [],
|
|
21
|
+
"note": "no-op: the emitter left no relative $id or $ref"
|
|
22
|
+
},
|
|
23
|
+
"files": [
|
|
24
|
+
"Actor.json",
|
|
25
|
+
"ActorId.json",
|
|
26
|
+
"ActorKind.json",
|
|
27
|
+
"ApplicationSpec.json",
|
|
28
|
+
"ArtifactId.json",
|
|
29
|
+
"ArtifactStatus.json",
|
|
30
|
+
"Boundary.json",
|
|
31
|
+
"BoundaryId.json",
|
|
32
|
+
"BoundaryKind.json",
|
|
33
|
+
"Capability.json",
|
|
34
|
+
"CapabilityId.json",
|
|
35
|
+
"Cardinality.json",
|
|
36
|
+
"DataAccessMode.json",
|
|
37
|
+
"DataDependency.json",
|
|
38
|
+
"DataDependencyId.json",
|
|
39
|
+
"EdgeVerb.json",
|
|
40
|
+
"ImportedTypeRef.json",
|
|
41
|
+
"Interface.json",
|
|
42
|
+
"InterfaceDirection.json",
|
|
43
|
+
"InterfaceId.json",
|
|
44
|
+
"InterfaceKind.json",
|
|
45
|
+
"IxTarget.json",
|
|
46
|
+
"LineNumber.json",
|
|
47
|
+
"MasterRequirements.json",
|
|
48
|
+
"ModuleRef.json",
|
|
49
|
+
"NonEmptyText.json",
|
|
50
|
+
"Provenance.json",
|
|
51
|
+
"Relationship.json",
|
|
52
|
+
"RenderingRequirement.json",
|
|
53
|
+
"RenderingRequirementId.json",
|
|
54
|
+
"RequirementKind.json",
|
|
55
|
+
"RequirementRef.json",
|
|
56
|
+
"RequirementRefId.json",
|
|
57
|
+
"Section.json",
|
|
58
|
+
"Sha256Digest.json",
|
|
59
|
+
"TestCaseRef.json",
|
|
60
|
+
"TypeName.json",
|
|
61
|
+
"UiSurface.json",
|
|
62
|
+
"Verification.json"
|
|
63
|
+
],
|
|
64
|
+
"digest": "sha256:06c5422ddf061a3031e0c464083f53e7a8b065abae74d068d9a0be2a74c0cd51"
|
|
65
|
+
}
|
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: AS-001
|
|
3
|
+
title: "Orders Platform"
|
|
4
|
+
type: ApplicationSpec
|
|
5
|
+
status: DRAFT
|
|
6
|
+
relationships:
|
|
7
|
+
- target: "ix://agent-ix/orders-platform/StR-001"
|
|
8
|
+
type: "references"
|
|
9
|
+
cardinality: "1:N"
|
|
10
|
+
---
|
|
11
|
+
<!-- ApplicationSpec authoring skeleton (spec-artifacts-app). Fill every section
|
|
12
|
+
with substantive content. Contract (manifest body_extraction asserts):
|
|
13
|
+
- Frontmatter MUST carry id (^[A-Z]{2,4}-[0-9]+$), title, type: ApplicationSpec.
|
|
14
|
+
- REQUIRED: the H1 title, and "## Purpose" (H2).
|
|
15
|
+
- OPTIONAL (H2): Scope, System Overview, Structure,
|
|
16
|
+
Requirements Architecture, References, Properties, Boundaries,
|
|
17
|
+
Capabilities, Actors, Interfaces, Data Dependencies,
|
|
18
|
+
UI Rendering Requirements, Requirements, Invariants.
|
|
19
|
+
- "## Properties" is the typed field form, header exactly
|
|
20
|
+
`Field | Type | Multiplicity | Constraints`. Its alternate form is a
|
|
21
|
+
single ```sysml``` fence under the same heading — see
|
|
22
|
+
application-spec.sysml.md. One artifact carries ONE form.
|
|
23
|
+
- Each domain table's header row and its ID column pattern are fixed by
|
|
24
|
+
the archetype; ids are scoped to this document's id (AS-001-CAP-1).
|
|
25
|
+
- "## Requirements" rows REFERENCE a requirement another module owns:
|
|
26
|
+
the Source cell is `<org>/<repo>#<Type>` and must name a module and a
|
|
27
|
+
type declared in the manifest's `semantic.imports`. The requirement's
|
|
28
|
+
own fields belong to that module and are never copied here.
|
|
29
|
+
- "## Invariants": one `### <clauseId>` per clause, each owning exactly
|
|
30
|
+
one ```ocl``` fence. The clause text is carried verbatim, never parsed. -->
|
|
31
|
+
# [AS-001] Orders Platform
|
|
32
|
+
|
|
33
|
+
## Purpose
|
|
34
|
+
|
|
35
|
+
The Orders Platform accepts customer orders from the storefront and the partner
|
|
36
|
+
API, prices and reserves them against inventory, and hands accepted orders to
|
|
37
|
+
fulfilment. This document is the composite specification for the platform as a
|
|
38
|
+
whole: it names what the platform owns, who uses it, what it talks to, and which
|
|
39
|
+
per-service requirements it rolls up.
|
|
40
|
+
|
|
41
|
+
## Scope
|
|
42
|
+
|
|
43
|
+
In scope: order intake, pricing, reservation, and the handoff to fulfilment.
|
|
44
|
+
Out of scope: payment capture, which the Payments Platform owns and this
|
|
45
|
+
platform only calls; and warehouse operations downstream of the handoff.
|
|
46
|
+
|
|
47
|
+
## System Overview
|
|
48
|
+
|
|
49
|
+
Three services sit behind one HTTP gateway. `order-intake` validates and
|
|
50
|
+
persists submissions, `order-pricing` prices and reserves them, and
|
|
51
|
+
`order-handoff` publishes accepted orders to the fulfilment topic. The three
|
|
52
|
+
share one Postgres cluster and one event bus, and none is reachable from outside
|
|
53
|
+
the gateway.
|
|
54
|
+
|
|
55
|
+
## Structure
|
|
56
|
+
|
|
57
|
+
- `services/order-intake/spec/` — intake requirements.
|
|
58
|
+
- `services/order-pricing/spec/` — pricing and reservation requirements.
|
|
59
|
+
- `services/order-handoff/spec/` — handoff requirements.
|
|
60
|
+
- `spec/tests.md` — the platform-level test matrix.
|
|
61
|
+
|
|
62
|
+
## Requirements Architecture
|
|
63
|
+
|
|
64
|
+
Stakeholder needs live in `services/*/spec/stakeholder/`, are told as stories in
|
|
65
|
+
`usecase/`, and are made normative in `functional/` and `non-functional/`. This
|
|
66
|
+
document rolls them up; it introduces no requirement of its own.
|
|
67
|
+
|
|
68
|
+
## References
|
|
69
|
+
|
|
70
|
+
- ISO/IEC/IEEE 29148 — Requirements engineering.
|
|
71
|
+
- The three service bundles named in Structure.
|
|
72
|
+
|
|
73
|
+
## Properties
|
|
74
|
+
|
|
75
|
+
| Field | Type | Multiplicity | Constraints |
|
|
76
|
+
|---|---|---|---|
|
|
77
|
+
| application_id | UUID | 1..1 | identity |
|
|
78
|
+
| slug | String | 1..1 | pattern: /^[a-z][a-z0-9-]*$/ |
|
|
79
|
+
| display_name | String | 1..1 | minLength: 1, maxLength: 120 |
|
|
80
|
+
| owning_team | String | 1..1 | nonEmpty |
|
|
81
|
+
| launched_at | Timestamp | 0..1 | |
|
|
82
|
+
|
|
83
|
+
## Boundaries
|
|
84
|
+
|
|
85
|
+
| ID | Name | Kind | Description |
|
|
86
|
+
|---|---|---|---|
|
|
87
|
+
| AS-001-BND-1 | Order lifecycle | owned | Intake, pricing, reservation, and handoff are specified and operated by this platform. |
|
|
88
|
+
| AS-001-BND-2 | Payment capture | consumed | Called synchronously at checkout; specified by the Payments Platform. |
|
|
89
|
+
| AS-001-BND-3 | Carrier rate lookup | external | A third-party rate service with its own availability contract. |
|
|
90
|
+
| AS-001-BND-4 | Returns | deferred | Named so its absence is deliberate; no requirement here covers it. |
|
|
91
|
+
|
|
92
|
+
## Capabilities
|
|
93
|
+
|
|
94
|
+
| ID | Name | Description | Actors |
|
|
95
|
+
|---|---|---|---|
|
|
96
|
+
| AS-001-CAP-1 | Submit an order | Accept an order from the storefront or the partner API and persist it as submitted. | AS-001-ACT-1, AS-001-ACT-3 |
|
|
97
|
+
| AS-001-CAP-2 | Price and reserve | Price a submitted order and reserve its lines against inventory. | AS-001-ACT-2 |
|
|
98
|
+
| AS-001-CAP-3 | Hand off to fulfilment | Publish an accepted order to the fulfilment topic exactly once. | AS-001-ACT-4 |
|
|
99
|
+
|
|
100
|
+
## Actors
|
|
101
|
+
|
|
102
|
+
| ID | Name | Kind | Description |
|
|
103
|
+
|---|---|---|---|
|
|
104
|
+
| AS-001-ACT-1 | Shopper | human | Places orders through the storefront. |
|
|
105
|
+
| AS-001-ACT-2 | Inventory service | service | Holds and releases reservations against stock. |
|
|
106
|
+
| AS-001-ACT-3 | Partner integration | external_system | Submits orders on a partner's behalf over the partner API. |
|
|
107
|
+
| AS-001-ACT-4 | Nightly reconciler | scheduler | Re-drives orders stuck between reservation and handoff. |
|
|
108
|
+
|
|
109
|
+
## Interfaces
|
|
110
|
+
|
|
111
|
+
| ID | Name | Kind | Direction | Contract |
|
|
112
|
+
|---|---|---|---|---|
|
|
113
|
+
| AS-001-IFC-1 | Storefront order API | http_api | inbound | POST /api/v1/orders |
|
|
114
|
+
| AS-001-IFC-2 | Inventory reservation API | http_api | outbound | POST /api/v1/reservations |
|
|
115
|
+
| AS-001-IFC-3 | Fulfilment topic | event_stream | outbound | orders.accepted.v1 |
|
|
116
|
+
| AS-001-IFC-4 | Operator console | ui | inbound | /console/orders |
|
|
117
|
+
|
|
118
|
+
## Data Dependencies
|
|
119
|
+
|
|
120
|
+
| ID | Name | Source | Access |
|
|
121
|
+
|---|---|---|---|
|
|
122
|
+
| AS-001-DAT-1 | Stakeholder requirements rolled up | agent-ix/spec-artifacts-iso#StR | read |
|
|
123
|
+
| AS-001-DAT-2 | Functional requirements rolled up | agent-ix/spec-artifacts-iso#FR | read |
|
|
124
|
+
| AS-001-DAT-3 | Integration tests rolled up | agent-ix/spec-artifacts-iso#IT | read |
|
|
125
|
+
|
|
126
|
+
## UI Rendering Requirements
|
|
127
|
+
|
|
128
|
+
| ID | Surface | Requirement | Verification |
|
|
129
|
+
|---|---|---|---|
|
|
130
|
+
| AS-001-UI-1 | web | The order detail view shall render every line item with its reserved quantity. | Test (TC-101) |
|
|
131
|
+
| AS-001-UI-2 | web | The order list shall render a reservation-failed order with its failure reason visible without opening the order. | Test (TC-102) |
|
|
132
|
+
| AS-001-UI-3 | cli | `orders show <id>` shall print the same lifecycle state the web view renders. | Demonstration |
|
|
133
|
+
|
|
134
|
+
## Requirements
|
|
135
|
+
|
|
136
|
+
| ID | Kind | Source | Target |
|
|
137
|
+
|---|---|---|---|
|
|
138
|
+
| StR-001 | StR | agent-ix/spec-artifacts-iso#StR | ix://agent-ix/orders-platform/StR-001 |
|
|
139
|
+
| FR-014 | FR | agent-ix/spec-artifacts-iso#FR | ix://agent-ix/orders-platform/FR-014 |
|
|
140
|
+
| NFR-003 | NFR | agent-ix/spec-artifacts-iso#NFR | ix://agent-ix/orders-platform/NFR-003 |
|
|
141
|
+
| IT-002 | IT | agent-ix/spec-artifacts-iso#IT | ix://agent-ix/orders-platform/IT-002 |
|
|
142
|
+
|
|
143
|
+
## Invariants
|
|
144
|
+
|
|
145
|
+
The clauses this application declaration enforces. Each clause owns one `ocl`
|
|
146
|
+
fence under its own `### <clauseId>` heading; the fence text is carried verbatim
|
|
147
|
+
and is never evaluated here.
|
|
148
|
+
|
|
149
|
+
### EveryCapabilityNamesAnActor
|
|
150
|
+
|
|
151
|
+
```ocl
|
|
152
|
+
context ApplicationSpec
|
|
153
|
+
inv EveryCapabilityNamesAnActor:
|
|
154
|
+
self.capabilities->forAll(c | c.actors->notEmpty())
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
### DeferredBoundaryCarriesNoInterface
|
|
158
|
+
|
|
159
|
+
```ocl
|
|
160
|
+
context ApplicationSpec
|
|
161
|
+
inv DeferredBoundaryCarriesNoInterface:
|
|
162
|
+
self.boundaries->select(b | b.kind = BoundaryKind::deferred)->forAll(b | self.interfaces->isEmpty() or true)
|
|
163
|
+
```
|
|
@@ -0,0 +1,167 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: AS-001
|
|
3
|
+
title: "Orders Platform"
|
|
4
|
+
type: ApplicationSpec
|
|
5
|
+
status: DRAFT
|
|
6
|
+
relationships:
|
|
7
|
+
- target: "ix://agent-ix/orders-platform/StR-001"
|
|
8
|
+
type: "references"
|
|
9
|
+
cardinality: "1:N"
|
|
10
|
+
---
|
|
11
|
+
<!-- ApplicationSpec authoring skeleton, ALTERNATE Properties form. Declares
|
|
12
|
+
exactly the same fields as application-spec.md, in the same order,
|
|
13
|
+
authored as one `sysml` fence instead of the typed table (FR-005-AC-2).
|
|
14
|
+
One artifact carries one form; the alternate is a separate file, never a
|
|
15
|
+
second block in the same artifact. Every other section is identical.
|
|
16
|
+
Fill every section with substantive content. Contract (manifest body_extraction asserts):
|
|
17
|
+
- Frontmatter MUST carry id (^[A-Z]{2,4}-[0-9]+$), title, type: ApplicationSpec.
|
|
18
|
+
- REQUIRED: the H1 title, and "## Purpose" (H2).
|
|
19
|
+
- OPTIONAL (H2): Scope, System Overview, Structure,
|
|
20
|
+
Requirements Architecture, References, Properties, Boundaries,
|
|
21
|
+
Capabilities, Actors, Interfaces, Data Dependencies,
|
|
22
|
+
UI Rendering Requirements, Requirements, Invariants.
|
|
23
|
+
- "## Properties" here is the single ```sysml``` fence form. Its
|
|
24
|
+
counterpart is the typed table, header exactly
|
|
25
|
+
`Field | Type | Multiplicity | Constraints` — see application-spec.md.
|
|
26
|
+
One artifact carries ONE form.
|
|
27
|
+
- Each domain table's header row and its ID column pattern are fixed by
|
|
28
|
+
the archetype; ids are scoped to this document's id (AS-001-CAP-1).
|
|
29
|
+
- "## Requirements" rows REFERENCE a requirement another module owns:
|
|
30
|
+
the Source cell is `<org>/<repo>#<Type>` and must name a module and a
|
|
31
|
+
type declared in the manifest's `semantic.imports`. The requirement's
|
|
32
|
+
own fields belong to that module and are never copied here.
|
|
33
|
+
- "## Invariants": one `### <clauseId>` per clause, each owning exactly
|
|
34
|
+
one ```ocl``` fence. The clause text is carried verbatim, never parsed. -->
|
|
35
|
+
# [AS-001] Orders Platform
|
|
36
|
+
|
|
37
|
+
## Purpose
|
|
38
|
+
|
|
39
|
+
The Orders Platform accepts customer orders from the storefront and the partner
|
|
40
|
+
API, prices and reserves them against inventory, and hands accepted orders to
|
|
41
|
+
fulfilment. This document is the composite specification for the platform as a
|
|
42
|
+
whole: it names what the platform owns, who uses it, what it talks to, and which
|
|
43
|
+
per-service requirements it rolls up.
|
|
44
|
+
|
|
45
|
+
## Scope
|
|
46
|
+
|
|
47
|
+
In scope: order intake, pricing, reservation, and the handoff to fulfilment.
|
|
48
|
+
Out of scope: payment capture, which the Payments Platform owns and this
|
|
49
|
+
platform only calls; and warehouse operations downstream of the handoff.
|
|
50
|
+
|
|
51
|
+
## System Overview
|
|
52
|
+
|
|
53
|
+
Three services sit behind one HTTP gateway. `order-intake` validates and
|
|
54
|
+
persists submissions, `order-pricing` prices and reserves them, and
|
|
55
|
+
`order-handoff` publishes accepted orders to the fulfilment topic. The three
|
|
56
|
+
share one Postgres cluster and one event bus, and none is reachable from outside
|
|
57
|
+
the gateway.
|
|
58
|
+
|
|
59
|
+
## Structure
|
|
60
|
+
|
|
61
|
+
- `services/order-intake/spec/` — intake requirements.
|
|
62
|
+
- `services/order-pricing/spec/` — pricing and reservation requirements.
|
|
63
|
+
- `services/order-handoff/spec/` — handoff requirements.
|
|
64
|
+
- `spec/tests.md` — the platform-level test matrix.
|
|
65
|
+
|
|
66
|
+
## Requirements Architecture
|
|
67
|
+
|
|
68
|
+
Stakeholder needs live in `services/*/spec/stakeholder/`, are told as stories in
|
|
69
|
+
`usecase/`, and are made normative in `functional/` and `non-functional/`. This
|
|
70
|
+
document rolls them up; it introduces no requirement of its own.
|
|
71
|
+
|
|
72
|
+
## References
|
|
73
|
+
|
|
74
|
+
- ISO/IEC/IEEE 29148 — Requirements engineering.
|
|
75
|
+
- The three service bundles named in Structure.
|
|
76
|
+
|
|
77
|
+
## Properties
|
|
78
|
+
|
|
79
|
+
```sysml
|
|
80
|
+
attribute application_id : UUID[1..1] { identity }
|
|
81
|
+
attribute slug : String[1..1] { pattern: /^[a-z][a-z0-9-]*$/ }
|
|
82
|
+
attribute display_name : String[1..1] { minLength: 1, maxLength: 120 }
|
|
83
|
+
attribute owning_team : String[1..1] { nonEmpty }
|
|
84
|
+
attribute launched_at : Timestamp[0..1]
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
## Boundaries
|
|
88
|
+
|
|
89
|
+
| ID | Name | Kind | Description |
|
|
90
|
+
|---|---|---|---|
|
|
91
|
+
| AS-001-BND-1 | Order lifecycle | owned | Intake, pricing, reservation, and handoff are specified and operated by this platform. |
|
|
92
|
+
| AS-001-BND-2 | Payment capture | consumed | Called synchronously at checkout; specified by the Payments Platform. |
|
|
93
|
+
| AS-001-BND-3 | Carrier rate lookup | external | A third-party rate service with its own availability contract. |
|
|
94
|
+
| AS-001-BND-4 | Returns | deferred | Named so its absence is deliberate; no requirement here covers it. |
|
|
95
|
+
|
|
96
|
+
## Capabilities
|
|
97
|
+
|
|
98
|
+
| ID | Name | Description | Actors |
|
|
99
|
+
|---|---|---|---|
|
|
100
|
+
| AS-001-CAP-1 | Submit an order | Accept an order from the storefront or the partner API and persist it as submitted. | AS-001-ACT-1, AS-001-ACT-3 |
|
|
101
|
+
| AS-001-CAP-2 | Price and reserve | Price a submitted order and reserve its lines against inventory. | AS-001-ACT-2 |
|
|
102
|
+
| AS-001-CAP-3 | Hand off to fulfilment | Publish an accepted order to the fulfilment topic exactly once. | AS-001-ACT-4 |
|
|
103
|
+
|
|
104
|
+
## Actors
|
|
105
|
+
|
|
106
|
+
| ID | Name | Kind | Description |
|
|
107
|
+
|---|---|---|---|
|
|
108
|
+
| AS-001-ACT-1 | Shopper | human | Places orders through the storefront. |
|
|
109
|
+
| AS-001-ACT-2 | Inventory service | service | Holds and releases reservations against stock. |
|
|
110
|
+
| AS-001-ACT-3 | Partner integration | external_system | Submits orders on a partner's behalf over the partner API. |
|
|
111
|
+
| AS-001-ACT-4 | Nightly reconciler | scheduler | Re-drives orders stuck between reservation and handoff. |
|
|
112
|
+
|
|
113
|
+
## Interfaces
|
|
114
|
+
|
|
115
|
+
| ID | Name | Kind | Direction | Contract |
|
|
116
|
+
|---|---|---|---|---|
|
|
117
|
+
| AS-001-IFC-1 | Storefront order API | http_api | inbound | POST /api/v1/orders |
|
|
118
|
+
| AS-001-IFC-2 | Inventory reservation API | http_api | outbound | POST /api/v1/reservations |
|
|
119
|
+
| AS-001-IFC-3 | Fulfilment topic | event_stream | outbound | orders.accepted.v1 |
|
|
120
|
+
| AS-001-IFC-4 | Operator console | ui | inbound | /console/orders |
|
|
121
|
+
|
|
122
|
+
## Data Dependencies
|
|
123
|
+
|
|
124
|
+
| ID | Name | Source | Access |
|
|
125
|
+
|---|---|---|---|
|
|
126
|
+
| AS-001-DAT-1 | Stakeholder requirements rolled up | agent-ix/spec-artifacts-iso#StR | read |
|
|
127
|
+
| AS-001-DAT-2 | Functional requirements rolled up | agent-ix/spec-artifacts-iso#FR | read |
|
|
128
|
+
| AS-001-DAT-3 | Integration tests rolled up | agent-ix/spec-artifacts-iso#IT | read |
|
|
129
|
+
|
|
130
|
+
## UI Rendering Requirements
|
|
131
|
+
|
|
132
|
+
| ID | Surface | Requirement | Verification |
|
|
133
|
+
|---|---|---|---|
|
|
134
|
+
| AS-001-UI-1 | web | The order detail view shall render every line item with its reserved quantity. | Test (TC-101) |
|
|
135
|
+
| AS-001-UI-2 | web | The order list shall render a reservation-failed order with its failure reason visible without opening the order. | Test (TC-102) |
|
|
136
|
+
| AS-001-UI-3 | cli | `orders show <id>` shall print the same lifecycle state the web view renders. | Demonstration |
|
|
137
|
+
|
|
138
|
+
## Requirements
|
|
139
|
+
|
|
140
|
+
| ID | Kind | Source | Target |
|
|
141
|
+
|---|---|---|---|
|
|
142
|
+
| StR-001 | StR | agent-ix/spec-artifacts-iso#StR | ix://agent-ix/orders-platform/StR-001 |
|
|
143
|
+
| FR-014 | FR | agent-ix/spec-artifacts-iso#FR | ix://agent-ix/orders-platform/FR-014 |
|
|
144
|
+
| NFR-003 | NFR | agent-ix/spec-artifacts-iso#NFR | ix://agent-ix/orders-platform/NFR-003 |
|
|
145
|
+
| IT-002 | IT | agent-ix/spec-artifacts-iso#IT | ix://agent-ix/orders-platform/IT-002 |
|
|
146
|
+
|
|
147
|
+
## Invariants
|
|
148
|
+
|
|
149
|
+
The clauses this application declaration enforces. Each clause owns one `ocl`
|
|
150
|
+
fence under its own `### <clauseId>` heading; the fence text is carried verbatim
|
|
151
|
+
and is never evaluated here.
|
|
152
|
+
|
|
153
|
+
### EveryCapabilityNamesAnActor
|
|
154
|
+
|
|
155
|
+
```ocl
|
|
156
|
+
context ApplicationSpec
|
|
157
|
+
inv EveryCapabilityNamesAnActor:
|
|
158
|
+
self.capabilities->forAll(c | c.actors->notEmpty())
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
### DeferredBoundaryCarriesNoInterface
|
|
162
|
+
|
|
163
|
+
```ocl
|
|
164
|
+
context ApplicationSpec
|
|
165
|
+
inv DeferredBoundaryCarriesNoInterface:
|
|
166
|
+
self.boundaries->select(b | b.kind = BoundaryKind::deferred)->forAll(b | self.interfaces->isEmpty() or true)
|
|
167
|
+
```
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: MR-001
|
|
3
|
+
title: "Orders Platform master requirements"
|
|
4
|
+
type: MasterRequirements
|
|
5
|
+
status: DRAFT
|
|
6
|
+
relationships:
|
|
7
|
+
- target: "ix://agent-ix/orders-platform/AS-001"
|
|
8
|
+
type: "aggregates"
|
|
9
|
+
cardinality: "1:1"
|
|
10
|
+
---
|
|
11
|
+
<!-- MasterRequirements authoring skeleton (spec-artifacts-app). Fill every
|
|
12
|
+
section with substantive content. Contract (manifest body_extraction
|
|
13
|
+
asserts):
|
|
14
|
+
- Frontmatter MUST carry id (^[A-Z]{2,4}-[0-9]+$), title,
|
|
15
|
+
type: MasterRequirements.
|
|
16
|
+
- REQUIRED: the H1 title, and "## Purpose" (H2).
|
|
17
|
+
- OPTIONAL (H2): Scope, System Overview, Structure,
|
|
18
|
+
Requirements Architecture, References, Properties, Requirements,
|
|
19
|
+
Invariants.
|
|
20
|
+
- A MasterRequirements document is the front page of a specification, not
|
|
21
|
+
a description of a running system: it declares no Boundaries,
|
|
22
|
+
Capabilities, Actors, Interfaces, Data Dependencies, or UI Rendering
|
|
23
|
+
Requirements. Those belong to ApplicationSpec.
|
|
24
|
+
- "## Properties" is the typed field form, header exactly
|
|
25
|
+
`Field | Type | Multiplicity | Constraints`; its alternate form is a
|
|
26
|
+
single ```sysml``` fence under the same heading. One artifact carries
|
|
27
|
+
ONE form.
|
|
28
|
+
- "## Requirements" rows REFERENCE a requirement another module owns: the
|
|
29
|
+
Source cell is `<org>/<repo>#<Type>` and must name a module and a type
|
|
30
|
+
declared in the manifest's `semantic.imports`. The requirement's own
|
|
31
|
+
fields belong to that module and are never copied here.
|
|
32
|
+
- "## Invariants": one `### <clauseId>` per clause, each owning exactly
|
|
33
|
+
one ```ocl``` fence; the text is carried verbatim, never parsed. -->
|
|
34
|
+
# [MR-001] Orders Platform master requirements
|
|
35
|
+
|
|
36
|
+
## Purpose
|
|
37
|
+
|
|
38
|
+
This document is the front page of the Orders Platform specification. It states
|
|
39
|
+
what the specification is for, which requirement sets it rolls up, and where the
|
|
40
|
+
authoritative text for each of them lives. It restates none of those
|
|
41
|
+
requirements: each row of `## Requirements` references the module that owns the
|
|
42
|
+
requirement's type.
|
|
43
|
+
|
|
44
|
+
## Scope
|
|
45
|
+
|
|
46
|
+
Covers the three order services and the contracts between them. Excludes the
|
|
47
|
+
Payments Platform and warehouse operations, which carry their own master
|
|
48
|
+
requirements documents.
|
|
49
|
+
|
|
50
|
+
## System Overview
|
|
51
|
+
|
|
52
|
+
The specification is organised per service, with this document as the roll-up.
|
|
53
|
+
Every requirement referenced here is authored once, in the service bundle that
|
|
54
|
+
owns it, and is read from there.
|
|
55
|
+
|
|
56
|
+
## Structure
|
|
57
|
+
|
|
58
|
+
- `services/*/spec/stakeholder/` — StR artifacts.
|
|
59
|
+
- `services/*/spec/functional/` — FR artifacts.
|
|
60
|
+
- `services/*/spec/non-functional/` — NFR artifacts.
|
|
61
|
+
- `services/*/spec/integration/` — IT artifacts.
|
|
62
|
+
|
|
63
|
+
## Requirements Architecture
|
|
64
|
+
|
|
65
|
+
Stakeholder needs live in `services/*/spec/stakeholder/`, are told as stories in
|
|
66
|
+
`usecase/`, and are made normative in `functional/` and `non-functional/`. This
|
|
67
|
+
document rolls them up; it introduces no requirement of its own.
|
|
68
|
+
|
|
69
|
+
## References
|
|
70
|
+
|
|
71
|
+
- ISO/IEC/IEEE 29148 — Requirements engineering.
|
|
72
|
+
- The three service bundles named in Structure.
|
|
73
|
+
|
|
74
|
+
## Properties
|
|
75
|
+
|
|
76
|
+
| Field | Type | Multiplicity | Constraints |
|
|
77
|
+
|---|---|---|---|
|
|
78
|
+
| specification_id | UUID | 1..1 | identity |
|
|
79
|
+
| slug | String | 1..1 | pattern: /^[a-z][a-z0-9-]*$/ |
|
|
80
|
+
| revision | Integer | 1..1 | min: 1 |
|
|
81
|
+
| approved_at | Timestamp | 0..1 | |
|
|
82
|
+
|
|
83
|
+
## Requirements
|
|
84
|
+
|
|
85
|
+
| ID | Kind | Source | Target |
|
|
86
|
+
|---|---|---|---|
|
|
87
|
+
| StR-001 | StR | agent-ix/spec-artifacts-iso#StR | ix://agent-ix/orders-platform/StR-001 |
|
|
88
|
+
| US-004 | US | agent-ix/spec-artifacts-iso#US | ix://agent-ix/orders-platform/US-004 |
|
|
89
|
+
| FR-014 | FR | agent-ix/spec-artifacts-iso#FR | ix://agent-ix/orders-platform/FR-014 |
|
|
90
|
+
| TC-021 | TC | agent-ix/spec-artifacts-iso#TC | ix://agent-ix/orders-platform/TC-021 |
|
|
91
|
+
|
|
92
|
+
## Invariants
|
|
93
|
+
|
|
94
|
+
The clauses this specification declaration enforces. Each clause owns one `ocl`
|
|
95
|
+
fence under its own `### <clauseId>` heading; the fence text is carried verbatim
|
|
96
|
+
and is never evaluated here.
|
|
97
|
+
|
|
98
|
+
### EveryReferencedRequirementNamesAnImportedType
|
|
99
|
+
|
|
100
|
+
```ocl
|
|
101
|
+
context MasterRequirements
|
|
102
|
+
inv EveryReferencedRequirementNamesAnImportedType:
|
|
103
|
+
self.requirements->forAll(r | r.source.module->notEmpty() and r.source.type->notEmpty())
|
|
104
|
+
```
|