@agent-ix/spec-artifacts-app 0.5.0 → 0.7.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.
Files changed (47) hide show
  1. package/README.md +39 -1
  2. package/manifest.yaml +274 -4
  3. package/mappings.schema.json +318 -0
  4. package/mappings.yaml +386 -0
  5. package/package.json +10 -2
  6. package/schemas/Actor.json +34 -0
  7. package/schemas/ActorId.json +7 -0
  8. package/schemas/ActorKind.json +13 -0
  9. package/schemas/ApplicationSpec.json +116 -0
  10. package/schemas/ArtifactId.json +7 -0
  11. package/schemas/ArtifactStatus.json +7 -0
  12. package/schemas/Boundary.json +34 -0
  13. package/schemas/BoundaryId.json +7 -0
  14. package/schemas/BoundaryKind.json +12 -0
  15. package/schemas/Capability.json +37 -0
  16. package/schemas/CapabilityId.json +7 -0
  17. package/schemas/Cardinality.json +7 -0
  18. package/schemas/DataAccessMode.json +11 -0
  19. package/schemas/DataDependency.json +33 -0
  20. package/schemas/DataDependencyId.json +7 -0
  21. package/schemas/EdgeVerb.json +7 -0
  22. package/schemas/ImportedTypeRef.json +21 -0
  23. package/schemas/Interface.json +38 -0
  24. package/schemas/InterfaceDirection.json +11 -0
  25. package/schemas/InterfaceId.json +7 -0
  26. package/schemas/InterfaceKind.json +15 -0
  27. package/schemas/IxTarget.json +7 -0
  28. package/schemas/LineNumber.json +8 -0
  29. package/schemas/MasterRequirements.json +80 -0
  30. package/schemas/ModuleRef.json +7 -0
  31. package/schemas/NonEmptyText.json +7 -0
  32. package/schemas/Provenance.json +25 -0
  33. package/schemas/Relationship.json +24 -0
  34. package/schemas/RenderingRequirement.json +34 -0
  35. package/schemas/RenderingRequirementId.json +7 -0
  36. package/schemas/RequirementKind.json +14 -0
  37. package/schemas/RequirementRef.json +33 -0
  38. package/schemas/RequirementRefId.json +7 -0
  39. package/schemas/Section.json +26 -0
  40. package/schemas/Sha256Digest.json +7 -0
  41. package/schemas/TestCaseRef.json +7 -0
  42. package/schemas/TypeName.json +7 -0
  43. package/schemas/UiSurface.json +7 -0
  44. package/schemas/Verification.json +29 -0
  45. package/skeletons/application-spec.md +163 -0
  46. package/skeletons/application-spec.sysml.md +167 -0
  47. package/skeletons/master-requirements.md +104 -0
package/README.md CHANGED
@@ -1,5 +1,7 @@
1
1
  # spec-artifacts-app
2
2
 
3
+ [![Discord](https://img.shields.io/badge/Discord-Join%20us-5865F2?logo=discord&logoColor=white)](https://discord.gg/6qsdhSPE)
4
+
3
5
  > Filament Module: application/composite spec artifact templates (ApplicationSpec, MasterRequirements) — absorbed spec-master-requirements
4
6
 
5
7
  Agent-IX Filament module loaded by [`quire-cli`](https://github.com/agent-ix/quire-cli) and [`quoin`](https://github.com/agent-ix/quoin).
@@ -32,6 +34,25 @@ quoin plugin install package:@agent-ix/spec-artifacts-app
32
34
  quire validate spec/**/*.md --module node_modules/@agent-ix/spec-artifacts-app
33
35
  ```
34
36
 
37
+ ## The semantic contract
38
+
39
+ Since 0.2.0 this module declares a **semantic data model per artifact type**, so a
40
+ consumer can read an application composite as a typed record instead of
41
+ re-parsing its prose:
42
+
43
+ - `typespec/main.tsp` is the source, importing `@agent-ix/semantic-core`.
44
+ - `schemas/<Model>.json` is the emitted JSON Schema 2020-12 bundle (39 files).
45
+ - `manifest.yaml` carries the quoin FR-070 `semantic` block, and every artifact
46
+ type references its schema by path.
47
+ - `mappings.yaml` declares, per record property, which Markdown form fills it and
48
+ whether that form round-trips byte-for-byte.
49
+ - `skeletons/` are executable fixtures: a typed `## Properties` table, a `sysml`
50
+ fence as its alternate form, and `ocl` clauses under `## Invariants`.
51
+
52
+ An application composite **references** what other modules own rather than
53
+ restating it: an aggregated requirement or a data source is an
54
+ `{module, type}` pair plus an id, never a copy of the imported type's fields.
55
+
35
56
  ## What's in this module
36
57
 
37
58
  This module gives you the top-level document kinds for specifying a whole application — the documents that gather requirements together and describe the system as a whole. They sit above the individual requirement artifacts (`StR`, `FR`, `NFR`, …) and tie them into one specification.
@@ -72,7 +93,10 @@ See https://github.com/agent-ix/quire-cli#usage-instructions.
72
93
  - **Build/CI:** GitHub Actions; dynamic Git-tag-based versioning; publishes wheel + sdist to Google Artifact Registry via `twine upload -r internal-pypi`.
73
94
 
74
95
  ```bash
75
- make install # install deps in Poetry venv
96
+ make install # poetry install: deps in the Poetry venv, including quire
97
+ make semantic-install # npm ci for the pinned TypeSpec toolchain
98
+ make schemas # emit the JSON Schemas and refresh the derived files
99
+ make schemas-check # fail when the committed schemas drift
76
100
  make test # run pytest
77
101
  make lint # ruff + black check
78
102
  make format # ruff + black format
@@ -81,4 +105,18 @@ make local-publish # build and publish to local PyPI (pypi.ix)
81
105
  make update-lock # update poetry.lock
82
106
  ```
83
107
 
108
+ Two environment preconditions, both deliberate and both recorded in NFR-001:
109
+
110
+ - `@agent-ix/semantic-core` resolves only from the registry your npm
111
+ configuration routes the `@agent-ix` scope to. The repository carries no
112
+ `.npmrc`, so the routing is your machine's; `agent-ix/filament-core-data#11`
113
+ tracks the public publish.
114
+ - The Quire wheel exposing `extract_semantic` is a `pyproject.toml` dev
115
+ dependency pinned to the `internal-pypi` source, provisioned by
116
+ `poetry install`. The semantic tests **fail** rather than skip when it is
117
+ absent, because a skipped row is not coverage.
118
+
119
+ The offline, no-network gate is a manual procedure: see
120
+ [docs/offline-gate.md](docs/offline-gate.md).
121
+
84
122
  CI requires the `GCP_SERVICE_ACCOUNT_KEY` secret plus `GCP_REGION`, `GCP_PROJECT_NAME`, and `GCP_PYPI` variables for Artifact Registry publishing.
package/manifest.yaml CHANGED
@@ -1,7 +1,29 @@
1
1
  manifest_version: 1.0.0
2
2
  name: spec-artifacts-app
3
- version: 0.1.0
4
- description: "Filament Module: application/composite spec artifact templates (ApplicationSpec, MasterRequirements) \u2014 absorbed spec-master-requirements"
3
+ version: 0.2.0
4
+ description: "Filament Module: application/composite spec artifact templates (ApplicationSpec, MasterRequirements) — absorbed spec-master-requirements"
5
+ # Semantic-module contract (quoin FR-070/FR-073, agent-ix/spec-artifacts-app#3).
6
+ # `imports` names every module whose types this module's artifacts reference;
7
+ # an artifact references an imported type through `{module, type}` and an id,
8
+ # never by restating the imported type's fields (FR-002-AC-10, FR-003-AC-4).
9
+ semantic:
10
+ contract_version: 1.0.0
11
+ semantic_core: 0.3.0
12
+ package: agent-ix/spec-artifacts-app
13
+ exports:
14
+ - ApplicationSpec
15
+ - MasterRequirements
16
+ # FR-035 types `imports` as `<org>/<repo>` -> exact semver, and nothing more.
17
+ # The *types* this module references from each imported package are declared
18
+ # in `mappings.yaml` under `imported_types`, because the contract has no place
19
+ # for them yet (agent-ix/quoin#339). The suite checks every `ImportedTypeRef`
20
+ # against both: the package here, the type there.
21
+ imports:
22
+ agent-ix/spec-artifacts-iso: 0.2.0
23
+ targets: [json-schema, markdown]
24
+ mappings: [frontmatter, section, typed-table, sysml-fence, ocl-clause, provenance]
25
+ compatibility_posture: additive
26
+ legacy_forms: warning
5
27
  archetypes:
6
28
  - kind: application-spec
7
29
  name: Application Spec
@@ -24,25 +46,273 @@ artifact_types:
24
46
  - name: ApplicationSpec
25
47
  grammar_ref: app-spec
26
48
  frontmatter_schema_ref: schemas/applicationspec-frontmatter.schema.json
49
+ data_schema:
50
+ schema: schemas/ApplicationSpec.json
27
51
  defaults:
28
- id_pattern: ApplicationSpec-{next:03d}
52
+ id_pattern: AS-{next:03d}
29
53
  allowed_links:
30
54
  - contains
31
55
  - depends_on
32
56
  - references
33
57
  examples: []
34
58
  lint_rules_ref: []
59
+ # Every locator this ticket adds is optional except `title` and `purpose`,
60
+ # which every application spec authored before the change already carries
61
+ # (NFR-001 metric 3, FR-005-CON-1).
62
+ body_extraction:
63
+ yield_pattern:
64
+ match:
65
+ title:
66
+ from: heading
67
+ level: 1
68
+ required: true
69
+ assert:
70
+ level: 1
71
+ purpose:
72
+ from: section_body
73
+ after_heading: Purpose
74
+ required: true
75
+ assert:
76
+ level: 2
77
+ scope:
78
+ from: section_body
79
+ after_heading: Scope
80
+ required: false
81
+ assert:
82
+ level: 2
83
+ system_overview:
84
+ from: section_body
85
+ after_heading: System Overview
86
+ required: false
87
+ assert:
88
+ level: 2
89
+ structure:
90
+ from: section_body
91
+ after_heading: Structure
92
+ required: false
93
+ assert:
94
+ level: 2
95
+ requirements_architecture:
96
+ from: section_body
97
+ after_heading: Requirements Architecture
98
+ required: false
99
+ assert:
100
+ level: 2
101
+ references:
102
+ from: section_body
103
+ after_heading: References
104
+ required: false
105
+ assert:
106
+ level: 2
107
+ boundaries_table:
108
+ from: table_row
109
+ under_section: Boundaries
110
+ required: false
111
+ assert:
112
+ columns:
113
+ - ID
114
+ - Name
115
+ - Kind
116
+ - Description
117
+ min_rows: 1
118
+ id_column: ID
119
+ id_pattern: ^{id}-BND-\d+$
120
+ capabilities_table:
121
+ from: table_row
122
+ under_section: Capabilities
123
+ required: false
124
+ assert:
125
+ columns:
126
+ - ID
127
+ - Name
128
+ - Description
129
+ - Actors
130
+ min_rows: 1
131
+ id_column: ID
132
+ id_pattern: ^{id}-CAP-\d+$
133
+ actors_table:
134
+ from: table_row
135
+ under_section: Actors
136
+ required: false
137
+ assert:
138
+ columns:
139
+ - ID
140
+ - Name
141
+ - Kind
142
+ - Description
143
+ min_rows: 1
144
+ id_column: ID
145
+ id_pattern: ^{id}-ACT-\d+$
146
+ interfaces_table:
147
+ from: table_row
148
+ under_section: Interfaces
149
+ required: false
150
+ assert:
151
+ columns:
152
+ - ID
153
+ - Name
154
+ - Kind
155
+ - Direction
156
+ - Contract
157
+ min_rows: 1
158
+ id_column: ID
159
+ id_pattern: ^{id}-IFC-\d+$
160
+ data_dependencies_table:
161
+ from: table_row
162
+ under_section: Data Dependencies
163
+ required: false
164
+ assert:
165
+ columns:
166
+ - ID
167
+ - Name
168
+ - Source
169
+ - Access
170
+ min_rows: 1
171
+ id_column: ID
172
+ id_pattern: ^{id}-DAT-\d+$
173
+ rendering_requirements_table:
174
+ from: table_row
175
+ under_section: UI Rendering Requirements
176
+ required: false
177
+ assert:
178
+ columns:
179
+ - ID
180
+ - Surface
181
+ - Requirement
182
+ - Verification
183
+ min_rows: 1
184
+ id_column: ID
185
+ id_pattern: ^{id}-UI-\d+$
186
+ requirements_table:
187
+ from: table_row
188
+ under_section: Requirements
189
+ required: false
190
+ assert:
191
+ columns:
192
+ - ID
193
+ - Kind
194
+ - Source
195
+ - Target
196
+ min_rows: 1
197
+ id_column: ID
198
+ id_pattern: ^(StR|US|FR|NFR|IT|TC)-\d+$
199
+ properties_table:
200
+ from: table_row
201
+ under_section: Properties
202
+ required: false
203
+ assert:
204
+ columns:
205
+ - Field
206
+ - Type
207
+ - Multiplicity
208
+ - Constraints
209
+ min_rows: 1
210
+ properties_fence:
211
+ from: code_block
212
+ language: sysml
213
+ under_section: Properties
214
+ required: false
215
+ multiple: false
216
+ invariants:
217
+ from: code_block
218
+ language: ocl
219
+ under_section: Invariants
220
+ required: false
221
+ multiple: true
35
222
  - name: MasterRequirements
36
223
  grammar_ref: app-spec
37
224
  frontmatter_schema_ref: schemas/masterrequirements-frontmatter.schema.json
225
+ data_schema:
226
+ schema: schemas/MasterRequirements.json
38
227
  defaults:
39
- id_pattern: MasterRequirements-{next:03d}
228
+ id_pattern: MR-{next:03d}
40
229
  allowed_links:
41
230
  - aggregates
42
231
  - depends_on
43
232
  - references
44
233
  examples: []
45
234
  lint_rules_ref: []
235
+ body_extraction:
236
+ yield_pattern:
237
+ match:
238
+ title:
239
+ from: heading
240
+ level: 1
241
+ required: true
242
+ assert:
243
+ level: 1
244
+ purpose:
245
+ from: section_body
246
+ after_heading: Purpose
247
+ required: true
248
+ assert:
249
+ level: 2
250
+ scope:
251
+ from: section_body
252
+ after_heading: Scope
253
+ required: false
254
+ assert:
255
+ level: 2
256
+ system_overview:
257
+ from: section_body
258
+ after_heading: System Overview
259
+ required: false
260
+ assert:
261
+ level: 2
262
+ structure:
263
+ from: section_body
264
+ after_heading: Structure
265
+ required: false
266
+ assert:
267
+ level: 2
268
+ requirements_architecture:
269
+ from: section_body
270
+ after_heading: Requirements Architecture
271
+ required: false
272
+ assert:
273
+ level: 2
274
+ references:
275
+ from: section_body
276
+ after_heading: References
277
+ required: false
278
+ assert:
279
+ level: 2
280
+ requirements_table:
281
+ from: table_row
282
+ under_section: Requirements
283
+ required: false
284
+ assert:
285
+ columns:
286
+ - ID
287
+ - Kind
288
+ - Source
289
+ - Target
290
+ min_rows: 1
291
+ id_column: ID
292
+ id_pattern: ^(StR|US|FR|NFR|IT|TC)-\d+$
293
+ properties_table:
294
+ from: table_row
295
+ under_section: Properties
296
+ required: false
297
+ assert:
298
+ columns:
299
+ - Field
300
+ - Type
301
+ - Multiplicity
302
+ - Constraints
303
+ min_rows: 1
304
+ properties_fence:
305
+ from: code_block
306
+ language: sysml
307
+ under_section: Properties
308
+ required: false
309
+ multiple: false
310
+ invariants:
311
+ from: code_block
312
+ language: ocl
313
+ under_section: Invariants
314
+ required: false
315
+ multiple: true
46
316
  doc_kinds:
47
317
  - application-spec
48
318
  - master-requirements
@@ -0,0 +1,318 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://schemas.agent-ix.org/agent-ix/spec-artifacts-app/mappings.schema.json",
4
+ "title": "spec-artifacts-app Markdown mapping declaration",
5
+ "description": "The schema mappings.yaml validates against (FR-004). A malformed mapping is a schema error here rather than a reader's surprise.",
6
+ "type": "object",
7
+ "additionalProperties": false,
8
+ "required": [
9
+ "mapping_version",
10
+ "module",
11
+ "kinds",
12
+ "imported_types",
13
+ "models"
14
+ ],
15
+ "properties": {
16
+ "mapping_version": {
17
+ "const": "1.0.0"
18
+ },
19
+ "module": {
20
+ "type": "string",
21
+ "pattern": "^[a-z][a-z0-9-]*/[a-z][a-z0-9-]*$"
22
+ },
23
+ "kinds": {
24
+ "description": "The mapping kinds this file uses; must equal the manifest's semantic.mappings list.",
25
+ "type": "array",
26
+ "minItems": 1,
27
+ "uniqueItems": true,
28
+ "items": {
29
+ "$ref": "#/$defs/kind"
30
+ }
31
+ },
32
+ "imported_types": {
33
+ "description": "Types this module references from each package semantic.imports pins. FR-035 types `imports` as package -> exact semver and carries no type list (agent-ix/quoin#339), so the list lives here.",
34
+ "type": "object",
35
+ "propertyNames": {
36
+ "pattern": "^[a-z][a-z0-9-]*/[a-z][a-z0-9-]*$"
37
+ },
38
+ "additionalProperties": {
39
+ "type": "array",
40
+ "minItems": 1,
41
+ "uniqueItems": true,
42
+ "items": {
43
+ "type": "string",
44
+ "pattern": "^[A-Za-z][A-Za-z0-9_-]*$"
45
+ }
46
+ }
47
+ },
48
+ "models": {
49
+ "type": "object",
50
+ "minProperties": 1,
51
+ "propertyNames": {
52
+ "pattern": "^[A-Z][A-Za-z0-9]*$"
53
+ },
54
+ "additionalProperties": {
55
+ "$ref": "#/$defs/model"
56
+ }
57
+ }
58
+ },
59
+ "$defs": {
60
+ "kind": {
61
+ "enum": [
62
+ "frontmatter",
63
+ "section",
64
+ "typed-table",
65
+ "sysml-fence",
66
+ "ocl-clause",
67
+ "provenance"
68
+ ]
69
+ },
70
+ "model": {
71
+ "type": "object",
72
+ "additionalProperties": false,
73
+ "required": [
74
+ "schema",
75
+ "artifact_type",
76
+ "authority",
77
+ "round_trip",
78
+ "dropped_frontmatter_keys",
79
+ "properties"
80
+ ],
81
+ "properties": {
82
+ "schema": {
83
+ "type": "string",
84
+ "pattern": "^schemas/[A-Za-z0-9]+\\.json$"
85
+ },
86
+ "artifact_type": {
87
+ "type": "string",
88
+ "minLength": 1
89
+ },
90
+ "authority": {
91
+ "const": "markdown"
92
+ },
93
+ "round_trip": {
94
+ "const": "derived"
95
+ },
96
+ "dropped_frontmatter_keys": {
97
+ "description": "Frontmatter keys the mapping drops. Declared so the loss is stated rather than silent; the emitted models are sealed, so an undeclared key cannot reach the record.",
98
+ "type": "array",
99
+ "uniqueItems": true,
100
+ "items": {
101
+ "type": "string",
102
+ "minLength": 1
103
+ }
104
+ },
105
+ "properties": {
106
+ "type": "object",
107
+ "minProperties": 1,
108
+ "propertyNames": {
109
+ "pattern": "^[a-z][A-Za-z0-9]*$"
110
+ },
111
+ "additionalProperties": {
112
+ "$ref": "#/$defs/property"
113
+ }
114
+ }
115
+ }
116
+ },
117
+ "property": {
118
+ "type": "object",
119
+ "additionalProperties": false,
120
+ "required": [
121
+ "kind",
122
+ "lossless"
123
+ ],
124
+ "properties": {
125
+ "kind": {
126
+ "$ref": "#/$defs/kind"
127
+ },
128
+ "lossless": {
129
+ "type": "boolean"
130
+ },
131
+ "required": {
132
+ "type": "boolean"
133
+ },
134
+ "prose_only": {
135
+ "description": "A structured section with no typed form. Requires a reason; the explicit designation FR-004-AC-2 demands.",
136
+ "type": "boolean"
137
+ },
138
+ "reason": {
139
+ "type": "string",
140
+ "minLength": 1
141
+ },
142
+ "locator": {
143
+ "type": "string",
144
+ "minLength": 1
145
+ },
146
+ "path": {
147
+ "type": "array",
148
+ "minItems": 1,
149
+ "items": {
150
+ "type": "string",
151
+ "minLength": 1
152
+ }
153
+ },
154
+ "heading": {
155
+ "type": "string",
156
+ "minLength": 1
157
+ },
158
+ "columns": {
159
+ "type": "array",
160
+ "minItems": 1,
161
+ "items": {
162
+ "type": "string",
163
+ "minLength": 1
164
+ }
165
+ },
166
+ "row_model": {
167
+ "type": "string",
168
+ "minLength": 1
169
+ },
170
+ "id_pattern": {
171
+ "type": "string",
172
+ "minLength": 1
173
+ },
174
+ "language": {
175
+ "type": "string",
176
+ "minLength": 1
177
+ },
178
+ "cell_parses": {
179
+ "type": "object",
180
+ "propertyNames": {
181
+ "pattern": "^[A-Za-z][A-Za-z0-9 ]*$"
182
+ },
183
+ "additionalProperties": {
184
+ "enum": [
185
+ "id",
186
+ "verification",
187
+ "imported-type-ref",
188
+ "id-list",
189
+ "enum",
190
+ "text",
191
+ "multiplicity",
192
+ "constraints"
193
+ ]
194
+ }
195
+ },
196
+ "alternate_form": {
197
+ "description": "The same declarations authored another way. One artifact carries one form; the alternate is a separate file.",
198
+ "type": "object",
199
+ "additionalProperties": false,
200
+ "required": [
201
+ "kind",
202
+ "heading",
203
+ "language"
204
+ ],
205
+ "properties": {
206
+ "kind": {
207
+ "$ref": "#/$defs/kind"
208
+ },
209
+ "heading": {
210
+ "type": "string",
211
+ "minLength": 1
212
+ },
213
+ "language": {
214
+ "type": "string",
215
+ "minLength": 1
216
+ },
217
+ "locator": {
218
+ "type": "string",
219
+ "minLength": 1
220
+ }
221
+ }
222
+ }
223
+ },
224
+ "allOf": [
225
+ {
226
+ "if": {
227
+ "properties": {
228
+ "prose_only": {
229
+ "const": true
230
+ }
231
+ },
232
+ "required": [
233
+ "prose_only"
234
+ ]
235
+ },
236
+ "then": {
237
+ "required": [
238
+ "reason"
239
+ ]
240
+ }
241
+ },
242
+ {
243
+ "if": {
244
+ "properties": {
245
+ "kind": {
246
+ "const": "typed-table"
247
+ }
248
+ },
249
+ "required": [
250
+ "kind"
251
+ ]
252
+ },
253
+ "then": {
254
+ "required": [
255
+ "heading",
256
+ "columns",
257
+ "locator"
258
+ ]
259
+ }
260
+ },
261
+ {
262
+ "if": {
263
+ "properties": {
264
+ "kind": {
265
+ "const": "section"
266
+ }
267
+ },
268
+ "required": [
269
+ "kind"
270
+ ]
271
+ },
272
+ "then": {
273
+ "required": [
274
+ "heading",
275
+ "locator"
276
+ ]
277
+ }
278
+ },
279
+ {
280
+ "if": {
281
+ "properties": {
282
+ "kind": {
283
+ "const": "frontmatter"
284
+ }
285
+ },
286
+ "required": [
287
+ "kind"
288
+ ]
289
+ },
290
+ "then": {
291
+ "required": [
292
+ "path"
293
+ ]
294
+ }
295
+ },
296
+ {
297
+ "if": {
298
+ "properties": {
299
+ "kind": {
300
+ "const": "ocl-clause"
301
+ }
302
+ },
303
+ "required": [
304
+ "kind"
305
+ ]
306
+ },
307
+ "then": {
308
+ "required": [
309
+ "heading",
310
+ "language",
311
+ "locator"
312
+ ]
313
+ }
314
+ }
315
+ ]
316
+ }
317
+ }
318
+ }