From adaac81c457b23ce6f43b1d42f4d6de24de02483 Mon Sep 17 00:00:00 2001 From: Agent IX Date: Mon, 9 Nov 2026 09:23:20 -0800 Subject: [PATCH 1/4] PLAT-277: do not require record keys whose source section is optional Configuration, Migration, Sli, Slo, Alert, Runbook, Incident and Deployment no longer require fields, clauses or operations; item rules still apply when the key is present. The migration-no-invariants negative fixture is a valid document now and is removed. Co-Authored-By: Claude Sonnet 5.5 --- spec/functional/FR-004-role-schemas.md | 31 +++++----- .../functional/FR-005-executable-skeletons.md | 8 +-- .../FR-006-optional-sections-optional-keys.md | 57 +++++++++++++++++++ spec/functional/index.md | 1 + spec/spec.md | 2 +- spec/tests.md | 22 +++---- spec_objects_operational/schemas/Alert.json | 3 - .../schemas/Configuration.json | 3 - .../schemas/Deployment.json | 4 -- .../schemas/Incident.json | 3 - .../schemas/Migration.json | 4 -- spec_objects_operational/schemas/Runbook.json | 3 - spec_objects_operational/schemas/Sli.json | 3 - spec_objects_operational/schemas/Slo.json | 4 -- .../negative/migration-no-invariants.md | 17 ------ tests/test_role_schemas.py | 49 ++++++++++++---- tests/test_skeletons_semantic.py | 4 +- typespec/main.tsp | 22 +++---- 18 files changed, 141 insertions(+), 99 deletions(-) create mode 100644 spec/functional/FR-006-optional-sections-optional-keys.md delete mode 100644 tests/fixtures/negative/migration-no-invariants.md diff --git a/spec/functional/FR-004-role-schemas.md b/spec/functional/FR-004-role-schemas.md index 40f7a60..d7aefa7 100644 --- a/spec/functional/FR-004-role-schemas.md +++ b/spec/functional/FR-004-role-schemas.md @@ -14,7 +14,7 @@ relationships: The TypeSpec source SHALL declare one model per operational object type whose emitted schema validates that type's declaration record -`{ fields?, clauses?, operations?, … }` with type-specific required keys, +`{ fields?, clauses?, operations?, … }` with no required key ([FR-006](./FR-006-optional-sections-optional-keys.md)), type-specific forbidden keys, and item rules, so that no type is a placeholder, each operational role refuses the records that violate its own rules, a standing definition is refused where an observed execution is required and the reverse, @@ -67,14 +67,14 @@ occurrence field at all. | Object type | Model | Required keys | Optional keys | Item rules | |---|---|---|---|---| -| configuration | `Configuration` | `fields` | `scopes: ScopeAssignment[]`, `configures: SemanticId[]`, `clauses`, `operations` | `fields` has ≥ 1 item, 0 identity fields (a parameter set is keyed by the configured object, not by itself) and 0 occurrence fields; `relations` forbidden | -| migration | `Migration` | `fields`, `clauses` | `rollback: RollbackDecl`, `migrates: SemanticId[]`, `dependsOn: SemanticId[]`, `operations` | `fields` has ≥ 1 item, 0 identity fields and 0 occurrence fields (an `applied_at` row is execution state); `clauses` has ≥ 1 item — a migration declares the safety condition it preserves; `relations` forbidden | -| sli | `Sli` | `fields` | `measures: SemanticId[]`, `clauses` | `fields` has ≥ 1 item, ≥ 1 measured field and 0 occurrence fields; `operations` forbidden — an SLI declares a measurement, not behaviour | -| slo | `Slo` | `fields`, `clauses` | `objective: ObjectiveDecl`, `constrains: SemanticId[]`, `dependsOn: SemanticId[]` | `fields` has ≥ 1 item, ≥ 1 measured field and 0 occurrence fields; `clauses` has ≥ 1 item — the objective is an invariant over the SLI; `operations` forbidden | -| alert | `Alert` | `clauses` | `conditions: AlertCondition[]`, `escalatesTo: SemanticId[]`, `references: SemanticId[]`, `operations` | `clauses` has ≥ 1 item — an alert is a firing condition; `fields` forbidden | -| runbook | `Runbook` | `operations` | `steps: RunbookStep[]`, `remediates: SemanticId[]`, `clauses` | `operations` has ≥ 1 item — a runbook declares the actions an operator performs; `fields` forbidden | -| incident | `Incident` | `fields` | `evidence: EvidenceRef[]`, `correlates: SemanticId[]`, `breaches: SemanticId[]`, `triggers: SemanticId[]`, `clauses`, `operations` | `fields` has ≥ 1 item, ≥ 1 identity field, and ≥ 1 occurrence field — an incident is an observed occurrence and is the only type that is | -| deployment | `Deployment` | `fields`, `operations` | `rollout: RolloutDecl`, `deploys: SemanticId[]`, `dependsOn: SemanticId[]`, `relations`, `clauses` | `fields` has ≥ 1 item, ≥ 1 identity field (the release identity) and 0 occurrence fields; `operations` has ≥ 1 item (the lifecycle actions) | +| configuration | `Configuration` | none (FR-006) | `scopes: ScopeAssignment[]`, `configures: SemanticId[]`, `clauses`, `operations` | `fields` has ≥ 1 item, 0 identity fields (a parameter set is keyed by the configured object, not by itself) and 0 occurrence fields; `relations` forbidden | +| migration | `Migration` | none (FR-006) | `rollback: RollbackDecl`, `migrates: SemanticId[]`, `dependsOn: SemanticId[]`, `operations` | `fields` has ≥ 1 item, 0 identity fields and 0 occurrence fields (an `applied_at` row is execution state); `clauses` has ≥ 1 item — a migration declares the safety condition it preserves; `relations` forbidden | +| sli | `Sli` | none (FR-006) | `measures: SemanticId[]`, `clauses` | `fields` has ≥ 1 item, ≥ 1 measured field and 0 occurrence fields; `operations` forbidden — an SLI declares a measurement, not behaviour | +| slo | `Slo` | none (FR-006) | `objective: ObjectiveDecl`, `constrains: SemanticId[]`, `dependsOn: SemanticId[]` | `fields` has ≥ 1 item, ≥ 1 measured field and 0 occurrence fields; `clauses` has ≥ 1 item — the objective is an invariant over the SLI; `operations` forbidden | +| alert | `Alert` | none (FR-006) | `conditions: AlertCondition[]`, `escalatesTo: SemanticId[]`, `references: SemanticId[]`, `operations` | `clauses` has ≥ 1 item — an alert is a firing condition; `fields` forbidden | +| runbook | `Runbook` | none (FR-006) | `steps: RunbookStep[]`, `remediates: SemanticId[]`, `clauses` | `operations` has ≥ 1 item — a runbook declares the actions an operator performs; `fields` forbidden | +| incident | `Incident` | none (FR-006) | `evidence: EvidenceRef[]`, `correlates: SemanticId[]`, `breaches: SemanticId[]`, `triggers: SemanticId[]`, `clauses`, `operations` | `fields` has ≥ 1 item, ≥ 1 identity field, and ≥ 1 occurrence field — an incident is an observed occurrence and is the only type that is | +| deployment | `Deployment` | none (FR-006) | `rollout: RolloutDecl`, `deploys: SemanticId[]`, `dependsOn: SemanticId[]`, `relations`, `clauses` | `fields` has ≥ 1 item, ≥ 1 identity field (the release identity) and 0 occurrence fields; `operations` has ≥ 1 item (the lifecycle actions) | - `ScopeAssignment` SHALL be `{ parameter: Identifier, scope: ConfigurationScope }` with `ConfigurationScope` the closed set `creation`, `runtime`, `session` — the same vocabulary the `configuration-scope` lint rule allows on the untyped `## Configuration` table. - `RollbackDecl` SHALL be `{ strategy: RollbackStrategy, clause?: ClauseRef, doc?: string }` with `RollbackStrategy` the closed set `reversible`, `forward_only`, `compensating`. @@ -110,7 +110,6 @@ occurrence field at all. | ID | Constraint | Type | Validation | |----|------------|------|------------| | FR-004-CON-1 | No model SHALL redeclare a semantic-core model or scalar; the module namespace contributes archetype shapes only (semantic-core NFR-014 kernel discipline). | Architecture | Test | -| FR-004-CON-2 | The empty record `{}` SHALL fail every one of the eight object-type schemas, because every type has a non-empty required set. | Integrity | Test | | FR-004-CON-3 | Exactly one model SHALL declare `evidence`. | Boundary | Test | | FR-004-CON-4 | No model SHALL declare a key holding an observation, sample, consumed budget, or execution timestamp. | Boundary | Test | | FR-004-CON-5 | No standing-definition model SHALL admit an occurrence field. | Boundary | Test | @@ -120,15 +119,15 @@ occurrence field at all. | ID | Criteria | Verification | |----|----------|--------------| | FR-004-AC-1 | Each of the eight shipped object-type schemas differs from every other in at least one required, forbidden, or item rule listed in the table; a schema with only `type: object` is absent. | Test | -| FR-004-AC-2 | A configuration record with one non-identity field validates against `Configuration.json`, with `scopes` accepted when present; the same record with an identity field fails; a record with no `fields` fails. | Test | -| FR-004-AC-3 | A migration record with one non-identity field and one clause validates against `Migration.json`, with `rollback` accepted when present; the same record without `clauses` fails; a record with an identity field fails. | Test | -| FR-004-AC-4 | An SLI record whose field carries a `type.unit` validates against `Sli.json`; the same record with the unit removed fails; a record carrying `operations` fails. | Test | -| FR-004-AC-5 | An SLO record with a measured field and one clause validates against `Slo.json`, with `objective` accepted when present; the same record without `clauses` fails; a record carrying `operations` fails. | Test | +| FR-004-AC-2 | A configuration record with one non-identity field validates against `Configuration.json`, with `scopes` accepted when present; the same record with an identity field fails; a record with an empty `fields` array fails. | Test | +| FR-004-AC-3 | A migration record with one non-identity field and one clause validates against `Migration.json`, with `rollback` accepted when present; the same record without `clauses` validates ([FR-006](./FR-006-optional-sections-optional-keys.md)); a record with an identity field fails. | Test | +| FR-004-AC-4 | An SLI record whose field carries a `type.unit` validates against `Sli.json`; the same record with the unit removed fails; a record without `fields` validates; a record carrying `operations` fails. | Test | +| FR-004-AC-5 | An SLO record with a measured field and one clause validates against `Slo.json`, with `objective` accepted when present; the same record without `clauses` validates ([FR-006](./FR-006-optional-sections-optional-keys.md)); a record carrying `operations` fails. | Test | | FR-004-AC-6 | An alert record with one clause validates against `Alert.json`, with `conditions` accepted when present; a record carrying `fields` fails; a record with an empty `clauses` array fails. | Test | | FR-004-AC-7 | A runbook record with one operation validates against `Runbook.json`, with `steps` accepted when present; a record carrying `fields` fails; a record with an empty `operations` array fails. | Test | | FR-004-AC-8 | An incident record with an identity field and a `Timestamp` field validates against `Incident.json`, with `evidence` accepted when present; the same record without the `Timestamp` field fails; the same record without the identity field fails. | Test | -| FR-004-AC-9 | A deployment record with an identity field and one operation validates against `Deployment.json`, with `rollout` accepted when present; the same record without `operations` fails; the same record with the identity flag removed fails. | Test | -| FR-004-AC-10 | The empty record `{}` fails all eight object-type schemas, and a record carrying an `observations` key fails every one of them. The second half holds for any unknown key, so it is evidence of the seal only; the type-specific purity evidence is FR-004-AC-14. | Test | +| FR-004-AC-9 | A deployment record with an identity field and one operation validates against `Deployment.json`, with `rollout` accepted when present; the same record without `operations` validates ([FR-006](./FR-006-optional-sections-optional-keys.md)); the same record with the identity flag removed fails. | Test | +| FR-004-AC-10 | The empty record `{}` validates against all eight object-type schemas ([FR-006](./FR-006-optional-sections-optional-keys.md)), and a record carrying an `observations` key fails every one of them. The second half holds for any unknown key, so it is evidence of the seal only; the type-specific purity evidence is FR-004-AC-14. | Test | | FR-004-AC-11 | `evidence` is declared by `Incident.json` and by no other shipped schema; an `evidence` entry whose `record` falls outside quoin FR-059's `$defs/identity` pattern fails, one carrying an `ix://` identity (also a valid FR-059 `record_id`) validates, and one whose `shape` is outside `EvidenceRecordShape` fails. | Test | | FR-004-AC-12 | A `type.target` of `ix://agent-ix/spec-objects-operational/unresolved/Mystery` is accepted by the schema (it is a `SemanticId`) and reported by the extractor as `semantic.unresolved-type`; a bare `Mystery` string is rejected by the schema. | Test | | FR-004-AC-13 | No module schema redeclares a semantic-core model; every grammar item across the eight object-type schemas is a `$ref` to semantic-core. | Test | diff --git a/spec/functional/FR-005-executable-skeletons.md b/spec/functional/FR-005-executable-skeletons.md index 14890d0..0ba2567 100644 --- a/spec/functional/FR-005-executable-skeletons.md +++ b/spec/functional/FR-005-executable-skeletons.md @@ -55,7 +55,7 @@ refuse. - Each alternate skeleton SHALL declare the same fields as its table skeleton, under that skeleton's frontmatter `id` and `title`; the module therefore ships two files under one id by intent, and the identity of their extracted `FieldDecl[]` is the obligation FR-005-AC-2 tests. - A bundle index built over these skeletons SHALL carry one entry per frontmatter `id`, not one per file, because the resolver matches entries rather than distinct ids and would otherwise raise `semantic.ambiguous-type` on a `Type` cell naming a title two files share. - The test suite SHALL verify FR-005-AC-3 through `extract_semantic` with that index and not through `validate_document`, which builds an index carrying `imports` only, so every non-kernel token falls to the `no-bundle-index` placeholder there; supplying an index to `validate_document` is `agent-ix/quire-rs`' concern, not this module's. -- Every skeleton SHALL author `## Invariants` with one `### ` per clause, each owning exactly one ```` ```ocl ```` fence, because every object-type model of [FR-004](./FR-004-role-schemas.md) admits `clauses` and `migration`, `slo`, and `alert` require at least one. +- Every skeleton SHALL author `## Invariants` with one `### ` per clause, each owning exactly one ```` ```ocl ```` fence, because every object-type model of [FR-004](./FR-004-role-schemas.md) admits `clauses`; none requires one ([FR-006](./FR-006-optional-sections-optional-keys.md)). - Each skeleton's frontmatter SHALL carry `object: ` beside `type: `, because Quire runs the semantic layer (extraction and record validation) on the `object:` archetype of a document; a skeleton without it validates its headings only. - The manifest SHALL gain a `required: false` `section_body` locator for every `## Properties`, `## Invariants`, and `## Operations` section a skeleton introduces, so the section is asserted by the manifest and remains optional for existing artifacts. - Each skeleton whose type requires `operations` (`runbook`, `deployment`) SHALL author `## Operations` with one `### ` per operation, an optional `| Param | Type | Multiplicity | Constraints |` table, a `Returns:` line where the operation returns a value, and optional `Pre:`/`Post:` lines that, when present, name clause ids declared in the same artifact. @@ -67,8 +67,8 @@ refuse. - Where a typed section and a kernel section describe the same declarations (the configuration `## Properties` table and its `## Configuration` table; the runbook `## Operations` and its `## Steps` prose; the deployment `## Operations` and its `## Topology` diagram), the typed section SHALL be the authority and the kernel section a derived, human-facing view; the `## Configuration` table stays the asserted form while `agent-ix/quoin#335` decides the `scopes` mapping. - Three further overlaps run the other way — the kernel form is required and the typed key is optional and unpopulated — and for each of them the kernel form SHALL remain the authority until `agent-ix/quoin#335` publishes the mapping that fills the typed key: the alert `## Flow` mermaid fence carries the burn-rate thresholds, windows and severities that `conditions` will carry; the slo frontmatter `target`/`window` pair carries the promise that `objective` will carry; the incident `## Timeline` carries the ordering that `evidence` and the occurrence fields will carry. - Where the kernel form is the authority, no test SHALL assert agreement between it and its typed key, because the typed key is absent from every extracted record today; agreement becomes assertable only when the mapping lands. -- Each negative fixture SHALL fail `validate_document` with an error whose message carries the fixture's `expect:` code, covering at least: a configuration with an identity row (`semantic.record-invalid`), a migration with no `## Invariants` (`semantic.record-invalid`), a migration carrying an `applied_at` `Timestamp` row (`semantic.record-invalid`), an SLI whose only field carries no unit (`semantic.record-invalid`), an alert carrying a `## Properties` table (`semantic.record-invalid`), a runbook whose `## Operations` declares no operation (`semantic.record-invalid`), an incident with no `Timestamp` row (`semantic.record-invalid`), a `## Properties` section carrying both a table and a fence (`semantic.properties-both-forms`), an operation whose `Post:` names an undeclared clause (`semantic.dangling-clause-ref`), and a `Type` token that is not an `Identifier` (`semantic.invalid-type-token`); the last three re-check the engine's published diagnostics under this module's schemas rather than re-specify them. -- Because seven of the ten fixtures expect the same `semantic.record-invalid` code, each such fixture SHALL additionally carry a `detail:` frontmatter key naming a substring of the failing schema location, keyword, or offending declaration that no other fixture's message carries. +- Each negative fixture SHALL fail `validate_document` with an error whose message carries the fixture's `expect:` code, covering at least: a configuration with an identity row (`semantic.record-invalid`), a migration carrying an `applied_at` `Timestamp` row (`semantic.record-invalid`), an SLI whose only field carries no unit (`semantic.record-invalid`), an alert carrying a `## Properties` table (`semantic.record-invalid`), a runbook whose `## Operations` declares no operation (`semantic.record-invalid`), an incident with no `Timestamp` row (`semantic.record-invalid`), a `## Properties` section carrying both a table and a fence (`semantic.properties-both-forms`), an operation whose `Post:` names an undeclared clause (`semantic.dangling-clause-ref`), and a `Type` token that is not an `Identifier` (`semantic.invalid-type-token`); the last three re-check the engine's published diagnostics under this module's schemas rather than re-specify them. +- Because six of the nine fixtures expect the same `semantic.record-invalid` code, each such fixture SHALL additionally carry a `detail:` frontmatter key naming a substring of the failing schema location, keyword, or offending declaration that no other fixture's message carries. - The negative-fixture test SHALL assert both the `expect:` code and the `detail:` substring, so a fixture cannot pass on a refusal it did not intend. - The module SHALL declare `quire` in `pyproject.toml` as a dev dependency pinned to the `internal-pypi` source, so `poetry install` provisions the engine and no lookup falls through to public PyPI, where `quire` names an unrelated package. - If the installed Quire wheel is absent or lacks `extract_semantic`, then every semantic test SHALL fail — not skip — with a message naming the missing function and `poetry install`, so that no matrix row can pass or be reported green without the engine under test. @@ -89,7 +89,7 @@ refuse. | FR-005-AC-2 | For `configuration`, `sli`, and `deployment`, the table and `sysml` skeletons extract to identical normalized `fields` with `fieldsForm` `table` and `fence` respectively. | Test | | FR-005-AC-3 | Under a bundle index built from the skeleton frontmatter, every skeleton extracts with zero `error` diagnostics and zero `semantic.unresolved-type` findings, and every non-kernel `type.target` starts with `ix://agent-ix/spec-objects-operational/type/`. | Test | | FR-005-AC-4 | Each skeleton's `availability` states match its type: `fields` `available` for the six types that require `fields` and `not_applicable` for `alert` and `runbook`; `operations` `available` for `runbook` and `deployment`; `clauses` `available` for every skeleton. | Test | -| FR-005-AC-5 | Every negative fixture fails validation with an error message containing both its `expect:` code and its `detail:` substring, and at least the ten cases listed in Behavior are present. | Test | +| FR-005-AC-5 | Every negative fixture fails validation with an error message containing both its `expect:` code and its `detail:` substring, and at least the nine cases listed in Behavior are present. | Test | | FR-005-AC-6 | Every skeleton's H2 set equals a subset of the headings the manifest asserts for its type and includes every `required: true` heading. | Test | | FR-005-AC-7 | The skeleton for each of the eight types has no placeholder token and every asserted section body is non-empty. | Test | | FR-005-AC-8 | Every skeleton `title` matches the `Identifier` pattern, is unique across the skeletons, and is not a `KernelScalar` name; every skeleton frontmatter carries `object` equal to `type`. | Test | diff --git a/spec/functional/FR-006-optional-sections-optional-keys.md b/spec/functional/FR-006-optional-sections-optional-keys.md new file mode 100644 index 0000000..43b019b --- /dev/null +++ b/spec/functional/FR-006-optional-sections-optional-keys.md @@ -0,0 +1,57 @@ +--- +id: FR-006 +title: "Require a declaration key only when its source section is required" +type: FR +relationships: + - target: "ix://agent-ix/spec-objects-operational/US-001" + type: "implements" + - target: "ix://agent-ix/spec-objects-operational/FR-004" + type: "depends_on" + - target: "ix://agent-ix/spec-objects-operational/FR-005" + type: "depends_on" +--- +# FR-006: Require a declaration key only when its source section is required + +## Description + +An object type's declaration schema SHALL NOT require a record key whose source +section the same module's manifest locator marks optional (`required: false`), +so that a document satisfying every mandatory locator is not refused as +`semantic.record-invalid` for a key it was allowed to omit. + +## Inputs + +- The manifest `properties`, `invariants` and `operations` locators of the eight + object types, all `required: false`. +- The declaration record Quire assembles per artifact, which omits a key whose + section is absent ([FR-004](./FR-004-role-schemas.md) Inputs). + +## Outputs + +- `Configuration`, `Migration`, `Sli`, `Slo`, `Alert`, `Runbook`, `Incident` and + `Deployment` list no required key. + +## Behavior + +- A key made optional here keeps every item rule it had: `minItems`, `contains` + and the occurrence-field rules apply to the key whenever it is present. +- The absence of `fields`, `clauses` or `operations` is a valid declaration, not + a defect. +- Locators stay as they are: no section is made mandatory by this requirement. + +## Constraints + +| ID | Constraint | Type | Validation | +|----|------------|------|------------| +| FR-006-CON-1 | A schema SHALL require a key only where a required manifest locator feeds it; no operational record key has one. | Integrity | Test | + +## Acceptance Criteria + +| ID | Criteria | Verification | +|----|----------|--------------| +| FR-006-AC-1 | No shipped object-type schema lists a required key, and a record lacking `fields`, `clauses` or `operations` validates against each type that declares the key. | Test | +| FR-006-AC-2 | A present key is still checked: an empty `fields`, `clauses` or `operations` array, an `Slo` field without a unit, an `Incident` without an occurrence field, or a `Deployment` with an empty `operations` array fails. | Test | + +## Dependencies + +- **Upstream**: [FR-004](./FR-004-role-schemas.md), [FR-005](./FR-005-executable-skeletons.md) diff --git a/spec/functional/index.md b/spec/functional/index.md index 21a5fec..4271633 100644 --- a/spec/functional/index.md +++ b/spec/functional/index.md @@ -12,3 +12,4 @@ description: "Index of artifacts in this directory." * [FR-003: Declare the semantic-module contract in the manifest](./FR-003-semantic-manifest-contract.md) * [FR-004: Give every operational object type a role-distinct declaration schema](./FR-004-role-schemas.md) * [FR-005: Make every skeleton an executable typed fixture](./FR-005-executable-skeletons.md) +* [FR-006: Require a declaration key only when its source section is required](./FR-006-optional-sections-optional-keys.md) diff --git a/spec/spec.md b/spec/spec.md index 6b2913d..d9cb786 100644 --- a/spec/spec.md +++ b/spec/spec.md @@ -128,7 +128,7 @@ through the maintainer's story of declaring those types against semantic-core (`usecase/`) to the functional requirements (`functional/`): FR-001 activates the manifest against `filament-core`; FR-002 emits the schemas; FR-003 declares the semantic contract in the manifest; FR-004 fixes each type's role-distinct -schema; FR-005 makes the skeletons executable fixtures. Integration tests in `integration/` verify +schema; FR-005 makes the skeletons executable fixtures; FR-006 keeps a declaration key optional where its source section is. Integration tests in `integration/` verify the activation and Quoin-install boundaries; the third external boundary, the Quire engine (loader, extraction, record surface), has no IT artifact of its own — the FR-003 and FR-005 test harness is this module's Quire contract test, diff --git a/spec/tests.md b/spec/tests.md index 354acc4..fabd439 100644 --- a/spec/tests.md +++ b/spec/tests.md @@ -70,8 +70,9 @@ those fail when the engine is absent (FR-005-AC-10). | FR-001 | FR-001-AC-1..4 | TC-001..TC-004 | 🚧 AC-2..AC-4 need a running filament-core | | FR-002 | FR-002-AC-2..4, FR-002-AC-6..14, FR-002-CON-1..4 | TC-011..TC-028 | ✅ | | FR-003 | FR-003-AC-1..8, FR-003-CON-1..3 | TC-030..TC-038 | ✅ AC-5 is a Demonstration; AC-6's naming half is an expected failure | -| FR-004 | FR-004-AC-1..15, FR-004-CON-1..5 | TC-040..TC-054 | ✅ AC-15's refusal half is an expected failure on quoin#335 | +| FR-004 | FR-004-AC-1..15, FR-004-CON-1, FR-004-CON-3..5 | TC-040..TC-054 | ✅ AC-15's refusal half is an expected failure on quoin#335 | | FR-005 | FR-005-AC-1..11, FR-005-CON-1..2 | TC-060..TC-072 | ✅ | +| FR-006 | FR-006-AC-1..2, FR-006-CON-1 | TC-092 | ✅ | ### Integration Test Coverage @@ -114,15 +115,15 @@ those fail when the engine is absent (FR-005-AC-10). | TC-037 | Every lexicon definition is one whole scalar, and the three issue #5 definitions carry their restored wording | Unit | P1 | FR-003-AC-7, FR-003-CON-3 | ✅ | | TC-038 | The `configuration-scope` lint rule is present unchanged with its three allowed values at `warning` severity | Unit | P1 | FR-003-AC-8 | ✅ | | TC-040 | Each of the eight schemas differs from every other in a required, forbidden, or item rule; none is `type: object` only | Unit | P0 | FR-004-AC-1 | ✅ | -| TC-041 | Configuration: non-identity record validates and accepts `scopes`; an identity field fails; no `fields` fails | Integration | P0 | FR-004-AC-2 | ✅ | -| TC-042 | Migration: non-identity record with one clause validates and accepts `rollback`; no `clauses` fails; an identity field fails | Integration | P0 | FR-004-AC-3 | ✅ | +| TC-041 | Configuration: non-identity record validates and accepts `scopes`; an identity field fails; no `fields` validates (FR-006); empty `fields` fails | Integration | P0 | FR-004-AC-2 | ✅ | +| TC-042 | Migration: non-identity record with one clause validates and accepts `rollback`; no `clauses` validates (FR-006); an identity field fails | Integration | P0 | FR-004-AC-3 | ✅ | | TC-043 | SLI: a unit-bearing field validates; the unit removed fails; `operations` fails | Integration | P0 | FR-004-AC-4 | ✅ | -| TC-044 | SLO: a unit-bearing field with one clause validates and accepts `objective`; no `clauses` fails; `operations` fails | Integration | P0 | FR-004-AC-5 | ✅ | -| TC-045 | Alert: one clause validates and accepts `conditions`; `fields` fails; empty `clauses` fails | Integration | P0 | FR-004-AC-6 | ✅ | -| TC-046 | Runbook: one operation validates and accepts `steps`; `fields` fails; empty `operations` fails | Integration | P0 | FR-004-AC-7 | ✅ | -| TC-047 | Incident: identity plus `Timestamp` validates and accepts `evidence`; either field removed fails | Integration | P0 | FR-004-AC-8 | ✅ | -| TC-048 | Deployment: identity field plus one operation validates and accepts `rollout`; no `operations` fails; no identity fails | Integration | P0 | FR-004-AC-9 | ✅ | -| TC-049 | The empty record and a record carrying `observations` fail all eight schemas | Integration | P0 | FR-004-AC-10, FR-004-CON-2, FR-004-CON-4 | ✅ | +| TC-044 | SLO: a unit-bearing field with one clause validates and accepts `objective`; no `clauses` validates (FR-006); `operations` fails | Integration | P0 | FR-004-AC-5 | ✅ | +| TC-045 | Alert: one clause validates and accepts `conditions`; no `clauses` validates (FR-006); `fields` fails; empty `clauses` fails | Integration | P0 | FR-004-AC-6 | ✅ | +| TC-046 | Runbook: one operation validates and accepts `steps`; no `operations` validates (FR-006); `fields` fails; empty `operations` fails | Integration | P0 | FR-004-AC-7 | ✅ | +| TC-047 | Incident: identity plus `Timestamp` validates and accepts `evidence`; either field removed fails; no `fields` validates (FR-006) | Integration | P0 | FR-004-AC-8 | ✅ | +| TC-048 | Deployment: identity field plus one operation validates and accepts `rollout`; no `operations` validates (FR-006); no identity fails | Integration | P0 | FR-004-AC-9 | ✅ | +| TC-049 | The empty record validates against all eight schemas (FR-006) and a record carrying `observations` fails every one | Integration | P0 | FR-004-AC-10, FR-004-CON-4 | ✅ | | TC-050 | `evidence` is declared by `Incident.json` alone; a bare-token `record` and an out-of-set `kind` each fail | Integration | P0 | FR-004-AC-11, FR-004-CON-3 | ✅ | | TC-051 | Placeholder `unresolved` target is accepted by the schema and reported by the extractor; a bare token is refused | Integration | P1 | FR-004-AC-12 | ✅ | | TC-052 | No module schema redeclares a semantic-core model; every grammar item is a `$ref` to semantic-core | Unit | P1 | FR-004-AC-13, FR-004-CON-1 | ✅ | @@ -132,7 +133,7 @@ those fail when the engine is absent (FR-005-AC-10). | TC-061 | Table and `sysml` skeletons extract to identical normalized fields with the recorded forms | Integration | P0 | FR-005-AC-2 | ✅ | | TC-062 | Under the skeleton bundle index every skeleton extracts with zero errors and zero unresolved tokens | Integration | P0 | FR-005-AC-3 | ✅ | | TC-063 | Availability states per skeleton (fields, clauses, operations) match the type's declared set | Integration | P1 | FR-005-AC-4 | ✅ | -| TC-064 | Every negative fixture fails with its `expect:` code AND its `detail:` substring, and the ten named cases exist | Integration | P0 | FR-005-AC-5 | ✅ | +| TC-064 | Every negative fixture fails with its `expect:` code AND its `detail:` substring, and the nine named cases exist | Integration | P0 | FR-005-AC-5 | ✅ | | TC-065 | Every skeleton's H2 set is asserted by the manifest and includes every required heading | Unit | P1 | FR-005-AC-6 | ✅ | | TC-066 | Every skeleton is placeholder-free with non-empty asserted sections | Unit | P2 | FR-005-AC-7 | ✅ | | TC-067 | Skeleton titles are distinct `Identifier`s outside `KernelScalar`, and `object` equals `type` in every skeleton frontmatter | Unit | P1 | FR-005-AC-8 | ✅ | @@ -142,6 +143,7 @@ those fail when the engine is absent (FR-005-AC-10). | TC-071 | With the Quire wheel absent, every semantic test fails naming `extract_semantic` and `poetry install`; none skips | Integration | P0 | FR-005-AC-10 | ✅ | | TC-072 | `pyproject.toml` declares `quire` as a dev dependency pinned to the `internal-pypi` source | Unit | P1 | FR-005-AC-11 | ✅ | | TC-091 | Quoin install roundtrip: record, install, list, derive, restore | Manual | P1 | IT-002-SC-01, IT-002-SC-02, IT-002-SC-03, IT-002-SC-04, IT-002-SC-05, IT-002-SC-06 | 🚧 the Quoin build is now available; the row waits on the operator opt-in | +| TC-092 | A record lacking the optional section key validates against all eight schemas; a present key is still checked by its item rules | Unit | P0 | FR-006-AC-1, FR-006-AC-2, FR-006-CON-1 | ✅ | ## Test Environment diff --git a/spec_objects_operational/schemas/Alert.json b/spec_objects_operational/schemas/Alert.json index 9a5545e..cae5ea9 100644 --- a/spec_objects_operational/schemas/Alert.json +++ b/spec_objects_operational/schemas/Alert.json @@ -35,9 +35,6 @@ } } }, - "required": [ - "clauses" - ], "unevaluatedProperties": { "not": {} }, diff --git a/spec_objects_operational/schemas/Configuration.json b/spec_objects_operational/schemas/Configuration.json index 9654fcb..d801094 100644 --- a/spec_objects_operational/schemas/Configuration.json +++ b/spec_objects_operational/schemas/Configuration.json @@ -40,9 +40,6 @@ } } }, - "required": [ - "fields" - ], "unevaluatedProperties": { "not": {} }, diff --git a/spec_objects_operational/schemas/Deployment.json b/spec_objects_operational/schemas/Deployment.json index 7956358..83d330f 100644 --- a/spec_objects_operational/schemas/Deployment.json +++ b/spec_objects_operational/schemas/Deployment.json @@ -48,10 +48,6 @@ } } }, - "required": [ - "fields", - "operations" - ], "unevaluatedProperties": { "not": {} }, diff --git a/spec_objects_operational/schemas/Incident.json b/spec_objects_operational/schemas/Incident.json index 7ddeebd..a15e933 100644 --- a/spec_objects_operational/schemas/Incident.json +++ b/spec_objects_operational/schemas/Incident.json @@ -50,9 +50,6 @@ } } }, - "required": [ - "fields" - ], "unevaluatedProperties": { "not": {} }, diff --git a/spec_objects_operational/schemas/Migration.json b/spec_objects_operational/schemas/Migration.json index 02f8c38..af8a5b3 100644 --- a/spec_objects_operational/schemas/Migration.json +++ b/spec_objects_operational/schemas/Migration.json @@ -44,10 +44,6 @@ } } }, - "required": [ - "fields", - "clauses" - ], "unevaluatedProperties": { "not": {} }, diff --git a/spec_objects_operational/schemas/Runbook.json b/spec_objects_operational/schemas/Runbook.json index b25b2d6..a70ed7f 100644 --- a/spec_objects_operational/schemas/Runbook.json +++ b/spec_objects_operational/schemas/Runbook.json @@ -29,9 +29,6 @@ } } }, - "required": [ - "operations" - ], "unevaluatedProperties": { "not": {} }, diff --git a/spec_objects_operational/schemas/Sli.json b/spec_objects_operational/schemas/Sli.json index 7c5a60e..e617541 100644 --- a/spec_objects_operational/schemas/Sli.json +++ b/spec_objects_operational/schemas/Sli.json @@ -26,9 +26,6 @@ } } }, - "required": [ - "fields" - ], "unevaluatedProperties": { "not": {} }, diff --git a/spec_objects_operational/schemas/Slo.json b/spec_objects_operational/schemas/Slo.json index b13f0a7..e0052e9 100644 --- a/spec_objects_operational/schemas/Slo.json +++ b/spec_objects_operational/schemas/Slo.json @@ -36,10 +36,6 @@ } } }, - "required": [ - "fields", - "clauses" - ], "unevaluatedProperties": { "not": {} }, diff --git a/tests/fixtures/negative/migration-no-invariants.md b/tests/fixtures/negative/migration-no-invariants.md deleted file mode 100644 index d39363c..0000000 --- a/tests/fixtures/negative/migration-no-invariants.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -id: negative-002 -title: "MigrationWithoutSafetyClause" -type: migration -object: migration -expect: semantic.record-invalid -detail: 'at clauses: "clauses" is a required property' -because: "Migration.json requires at least one clause; a migration that states no safety condition states nothing a reviewer can check" ---- -# [negative-002] MigrationWithoutSafetyClause - -## Properties - -| Field | Type | Multiplicity | Constraints | -|---|---|---|---| -| migration_version | String | 1..1 | pattern: /^[0-9]{14}$/ | -| target_table | String | 1..1 | minLength: 1 | diff --git a/tests/test_role_schemas.py b/tests/test_role_schemas.py index a2a1d97..9b4cab3 100644 --- a/tests/test_role_schemas.py +++ b/tests/test_role_schemas.py @@ -134,7 +134,8 @@ def test_configuration_requires_fields_and_refuses_an_identity_row(schema_regist assert not ok( configuration, {"fields": [field("config_id", "UUID", identity=True)]} ) - assert not ok(configuration, {}) + # FR-006: the key is optional, so its absence validates. + assert ok(configuration, {}) assert not ok(configuration, {"fields": []}) @@ -149,7 +150,8 @@ def test_migration_requires_a_safety_clause_and_refuses_an_identity_row( assert ok(migration, record) assert ok(migration, {**record, "rollback": {"strategy": "reversible"}}) assert not ok(migration, {**record, "rollback": {"strategy": "pray"}}) - assert not ok(migration, {"fields": record["fields"]}) + # FR-006: the key is optional, so its absence validates. + assert ok(migration, {"fields": record["fields"]}) assert not ok(migration, {**record, "clauses": []}) assert not ok( migration, @@ -163,7 +165,8 @@ def test_sli_requires_a_measured_field_and_refuses_operations(schema_registry): assert ok(sli, {"fields": [MEASURED]}) assert not ok(sli, {"fields": [field("latency", "Duration")]}) assert not ok(sli, {"fields": [MEASURED], "operations": [OPERATION]}) - assert not ok(sli, {}) + # FR-006: the key is optional, so its absence validates. + assert ok(sli, {}) @pytest.mark.trace("TC-044", "FR-004-AC-5") @@ -182,7 +185,8 @@ def test_slo_requires_a_measured_field_and_a_clause_and_refuses_operations( assert ok(slo, record) assert ok(slo, {**record, "objective": objective}) assert not ok(slo, {**record, "objective": {**objective, "window": "30 days"}}) - assert not ok(slo, {"fields": [MEASURED]}) + # FR-006: the key is optional, so its absence validates. + assert ok(slo, {"fields": [MEASURED]}) assert not ok(slo, {"fields": [field("ratio", "Decimal")], "clauses": [CLAUSE]}) assert not ok(slo, {**record, "operations": [OPERATION]}) @@ -207,7 +211,8 @@ def test_alert_requires_a_clause_and_refuses_fields(schema_registry): ) assert not ok(alert, {"clauses": [CLAUSE], "fields": [field("burn_rate")]}) assert not ok(alert, {"clauses": []}) - assert not ok(alert, {}) + # FR-006: the key is optional, so its absence validates. + assert ok(alert, {}) @pytest.mark.trace("TC-046", "FR-004-AC-7") @@ -223,7 +228,8 @@ def test_runbook_requires_operations_and_refuses_fields(schema_registry): runbook, {"operations": [OPERATION], "fields": [field("page_id", "UUID")]} ) assert not ok(runbook, {"operations": []}) - assert not ok(runbook, {}) + # FR-006: the key is optional, so its absence validates. + assert ok(runbook, {}) @pytest.mark.trace("TC-047", "FR-004-AC-8") @@ -240,7 +246,8 @@ def test_incident_requires_an_occurrence_identity_and_admits_evidence(schema_reg assert ok(incident, {"fields": [identity, OCCURRENCE], "evidence": [evidence]}) assert not ok(incident, {"fields": [identity]}) assert not ok(incident, {"fields": [OCCURRENCE]}) - assert not ok(incident, {}) + # FR-006: the key is optional, so its absence validates. + assert ok(incident, {}) @pytest.mark.trace("TC-048", "FR-004-AC-9") @@ -257,21 +264,25 @@ def test_deployment_requires_a_release_identity_and_lifecycle_operations( assert ok(deployment, record) assert ok(deployment, {**record, "rollout": {"strategy": "canary"}}) assert not ok(deployment, {**record, "rollout": {"strategy": "yolo"}}) - assert not ok(deployment, {"fields": record["fields"]}) + # FR-006: the key is optional, so its absence validates. + assert ok(deployment, {"fields": record["fields"]}) assert not ok(deployment, {**record, "operations": []}) assert not ok( deployment, {"fields": [field("release_id")], "operations": [OPERATION]} ) -@pytest.mark.trace("TC-049", "FR-004-AC-10", "FR-004-CON-2", "FR-004-CON-4") -def test_the_empty_record_and_an_observation_key_fail_every_type(schema_registry): +@pytest.mark.trace("TC-049", "FR-004-AC-10", "FR-004-CON-4") +def test_an_observation_key_fails_every_type_and_the_empty_record_validates( + schema_registry, +): """The `observations` half is seal evidence only: any unknown key fails a sealed schema. The type-specific purity evidence is the occurrence-row test below. """ for name in OBJECT_TYPES: validator = schema_registry(MODEL_OF[name]) - assert not ok(validator, {}), f"{name} accepted the empty record" + # FR-006: every record key is optional, so the empty record validates. + assert ok(validator, {}), f"{name} refused the empty record" polluted = dict(valid_record(name)) polluted["observations"] = [{"at": "2026-06-02T09:12:00Z", "value": 0.974}] assert not ok(validator, polluted), f"{name} accepted an observations key" @@ -472,3 +483,19 @@ def test_the_three_cross_key_reader_rules_are_refused(schema_registry): ], }, ) + + +@pytest.mark.trace("TC-092", "FR-006-AC-1", "FR-006-AC-2") +def test_a_record_lacking_an_optional_section_key_validates_and_the_key_stays_checked( + schema_registry, +): + """Hand-built: the record a document without the optional section yields.""" + for name in OBJECT_TYPES: + assert not schema_of(name).get("required"), name + assert not ok(schema_registry("Configuration"), {"fields": []}) + assert not ok(schema_registry("Migration"), {"clauses": []}) + assert not ok(schema_registry("Slo"), {"fields": [field("ratio", "Decimal")]}) + assert not ok(schema_registry("Alert"), {"clauses": []}) + assert not ok(schema_registry("Runbook"), {"operations": []}) + assert not ok(schema_registry("Incident"), {"fields": [OCCURRENCE]}) + assert not ok(schema_registry("Deployment"), {"operations": []}) diff --git a/tests/test_skeletons_semantic.py b/tests/test_skeletons_semantic.py index 04945aa..3edaafa 100644 --- a/tests/test_skeletons_semantic.py +++ b/tests/test_skeletons_semantic.py @@ -148,11 +148,11 @@ def test_availability_states_match_each_type( @pytest.mark.trace("TC-064", "FR-005-AC-5") def test_every_negative_fixture_fails_for_its_own_reason(quire_engine): - """Seven of the ten fixtures surface as `semantic.record-invalid`, so the + """Six of the nine fixtures surface as `semantic.record-invalid`, so the code alone does not tell them apart: each fixture also names a `detail:` substring no other fixture's message carries, and both are asserted.""" fixtures = sorted(NEGATIVE_DIR.glob("*.md")) - assert len(fixtures) >= 10, "the ten named negative cases are not all present" + assert len(fixtures) >= 9, "the nine named negative cases are not all present" expected_codes = { "semantic.record-invalid", "semantic.properties-both-forms", diff --git a/typespec/main.tsp b/typespec/main.tsp index 77ef88b..40cf218 100644 --- a/typespec/main.tsp +++ b/typespec/main.tsp @@ -276,7 +276,7 @@ model Configuration { @contains(IdentityField) @minContains(0) @maxContains(0) - fields: FieldDecl[]; + fields?: FieldDecl[]; scopes?: ScopeAssignment[]; configures?: SemanticId[]; @@ -308,10 +308,10 @@ model Migration { @contains(IdentityField) @minContains(0) @maxContains(0) - fields: FieldDecl[]; + fields?: FieldDecl[]; @minItems(1) - clauses: ClauseRef[]; + clauses?: ClauseRef[]; rollback?: RollbackDecl; migrates?: SemanticId[]; @@ -339,7 +339,7 @@ model Migration { model Sli { @minItems(1) @contains(MeasuredField) - fields: FieldDecl[]; + fields?: FieldDecl[]; measures?: SemanticId[]; clauses?: ClauseRef[]; @@ -365,10 +365,10 @@ model Sli { model Slo { @minItems(1) @contains(MeasuredField) - fields: FieldDecl[]; + fields?: FieldDecl[]; @minItems(1) - clauses: ClauseRef[]; + clauses?: ClauseRef[]; objective?: ObjectiveDecl; constrains?: SemanticId[]; @@ -385,7 +385,7 @@ model Slo { */ model Alert { @minItems(1) - clauses: ClauseRef[]; + clauses?: ClauseRef[]; conditions?: AlertCondition[]; escalatesTo?: SemanticId[]; @@ -403,7 +403,7 @@ model Alert { */ model Runbook { @minItems(1) - operations: OperationDecl[]; + operations?: OperationDecl[]; steps?: RunbookStep[]; remediates?: SemanticId[]; @@ -431,10 +431,10 @@ model Runbook { model Deployment { @minItems(1) @contains(IdentityField) - fields: FieldDecl[]; + fields?: FieldDecl[]; @minItems(1) - operations: OperationDecl[]; + operations?: OperationDecl[]; rollout?: RolloutDecl; deploys?: SemanticId[]; @@ -469,7 +469,7 @@ model Deployment { model Incident { @minItems(1) @contains(IdentityField) - fields: FieldDecl[]; + fields?: FieldDecl[]; evidence?: EvidenceRef[]; correlates?: SemanticId[]; From e2ca6210a0dbcb21c43eb016676ceb0617b904e6 Mon Sep 17 00:00:00 2001 From: Agent IX Date: Mon, 9 Nov 2026 09:40:44 -0800 Subject: [PATCH 2/4] PLAT-277: review fixes for the optional record keys Correct the TypeSpec doc comments (and the emitted descriptions) that still said a key is required, test what the acceptance criteria say, add document-level tests for a missing optional section, align FR-004 and FR-005 wording, drop FR-006-CON-1 and the hand-kept counts. Co-Authored-By: Claude Sonnet 5.5 --- plan/Plan-001-semantic-data-schemas/plan.md | 2 +- .../tasks/Task-005-executable-skeletons.md | 2 +- reviews/plat-277-soo-pr29-code-review.md | 64 +++++++++++++++++++ reviews/plat-277-soo-pr29-gap-analysis.md | 32 ++++++++++ reviews/plat-277-soo-pr29-spec-review.md | 37 +++++++++++ spec/functional/FR-004-role-schemas.md | 26 ++++---- .../functional/FR-005-executable-skeletons.md | 4 +- .../FR-006-optional-sections-optional-keys.md | 9 +-- spec/tests.md | 6 +- spec_objects_operational/schemas/Alert.json | 2 +- .../schemas/Configuration.json | 2 +- .../schemas/Incident.json | 2 +- .../schemas/Migration.json | 2 +- spec_objects_operational/schemas/Runbook.json | 2 +- spec_objects_operational/schemas/Slo.json | 2 +- tests/test_role_schemas.py | 6 +- tests/test_skeletons_semantic.py | 31 ++++++++- typespec/main.tsp | 24 +++---- 18 files changed, 208 insertions(+), 47 deletions(-) create mode 100644 reviews/plat-277-soo-pr29-code-review.md create mode 100644 reviews/plat-277-soo-pr29-gap-analysis.md create mode 100644 reviews/plat-277-soo-pr29-spec-review.md diff --git a/plan/Plan-001-semantic-data-schemas/plan.md b/plan/Plan-001-semantic-data-schemas/plan.md index ca2ed38..da8503d 100644 --- a/plan/Plan-001-semantic-data-schemas/plan.md +++ b/plan/Plan-001-semantic-data-schemas/plan.md @@ -154,7 +154,7 @@ hard failure — a skip that was hiding a broken locator lookup for `configurati - [x] **TC-061** (FR-005-AC-2, FR-005-CON-2): table and `sysml` skeletons extract to identical normalized fields with the recorded forms. - [x] **TC-062** (FR-005-AC-3): under the skeleton bundle index every skeleton extracts with zero errors and zero unresolved tokens. - [x] **TC-063** (FR-005-AC-4): availability states per skeleton match the type's declared set. -- [x] **TC-064** (FR-005-AC-5): every negative fixture fails with its `expect:` code and its `detail:` substring, and the ten named cases exist. +- [x] **TC-064** (FR-005-AC-5): every negative fixture fails with its `expect:` code and its `detail:` substring, and the named cases exist. - [x] **TC-068** (FR-005-AC-9): the sli/slo skeletons extract a unit-bearing field and the incident skeleton an identity and a `Timestamp` field. - [x] **TC-070** (FR-005-CON-2): a Properties section holding both a table and a fence is refused at the second form. - [x] **TC-071** (FR-005-AC-10): with the engine absent the semantic rows fail rather than skip, naming the provisioning path. diff --git a/plan/Plan-001-semantic-data-schemas/tasks/Task-005-executable-skeletons.md b/plan/Plan-001-semantic-data-schemas/tasks/Task-005-executable-skeletons.md index 1b511fb..efa20ae 100644 --- a/plan/Plan-001-semantic-data-schemas/tasks/Task-005-executable-skeletons.md +++ b/plan/Plan-001-semantic-data-schemas/tasks/Task-005-executable-skeletons.md @@ -43,7 +43,7 @@ that pin what the schemas and the engine refuse. ## Subtasks -- [x] **Typed `## Properties`.** The six types that require `fields` author one table with the header exactly `Field | Type | Multiplicity | Constraints`; `alert` and `runbook` carry no such section because their models forbid `fields`. +- [x] **Typed `## Properties`.** The six types that declare `fields` author one table with the header exactly `Field | Type | Multiplicity | Constraints`; `alert` and `runbook` carry no such section because their models forbid `fields`. - [x] **The item rules, authored.** `sli` and `slo` each carry a `Type` cell with a trailing bracketed unit; `incident` carries one `identity` row and one `Timestamp` row; `configuration` and `migration` carry neither an identity nor a `Timestamp` row. - [x] **`## Invariants`.** Every skeleton, one `### ` per clause, each owning exactly one ```ocl``` fence. - [x] **`## Operations`.** `runbook` and `deployment`, one `### ` per operation with an optional param table, a `Returns:` line and `Pre:`/`Post:` lines naming clauses declared in the same artifact. diff --git a/reviews/plat-277-soo-pr29-code-review.md b/reviews/plat-277-soo-pr29-code-review.md new file mode 100644 index 0000000..8a23b4f --- /dev/null +++ b/reviews/plat-277-soo-pr29-code-review.md @@ -0,0 +1,64 @@ +--- +id: SR-102 +title: "Code review — spec-objects-operational PR #29 (PLAT-277 F1 optional record keys)" +type: SpecReview +analysis: code-review +scope: "agent-ix/spec-objects-operational; typespec/main.tsp, spec_objects_operational/schemas/*.json, tests/test_role_schemas.py, tests/test_skeletons_semantic.py, tests/fixtures/negative/" +review_set: subset +--- +# Code review — spec-objects-operational PR #29 (PLAT-277 F1) + +## Summary + +Ticket: PLAT-277 (finding F1). Diff `origin/main...adaac81`: eight TypeSpec +models drop `required` on `fields` / `clauses` / `operations`, the eight +emitted schemas lose their `required` arrays, one negative fixture is deleted, +and the role-schema tests flip their absent-key assertions and gain TC-092. + +Verified independently: + +- Every relaxed key is fed only by a `required: false` locator in + `spec_objects_operational/manifest.yaml` (properties/invariants/operations + for all eight types, lines 93-331). No locator or construct is touched. +- Item rules (`minItems`, `contains`, the occurrence `allOf`) are unchanged in + every schema; only the `required` arrays are removed. +- Regeneration: fetched the real pinned `@agent-ix/semantic-core@0.3.2` from + GitHub Packages (sha512 equals `package-lock.json` integrity), ran `npm ci`, + then `node scripts/generate-schemas.mjs --check` (27 match) and a full + regenerate with clean `git status`, on both the PR head and `origin/main`. + The coder's 0.3.3-relabelled emission is therefore confirmed byte-for-byte + against the real toolchain. +- Tests (quire 0.54.0 wheel, the only one reachable): PR head 145 passed / + 6 failed; `origin/main` 144 passed / 6 failed. The 6 failing tests are the + same set with identical error lines on both trees (incident skeleton + `semantic.record-invalid`, alert-with-properties detail mismatch, unhashable + dict, empty extraction). Pre-existing engine skew, not introduced here. +- FCD construct consistency (filament-core-data + `crates/extraction-frontend/src/constructs.rs` `shape()`): the construct a + type lowers to comes from its manifest `object_types[].construct` block + (`bundle.rs` `archetype.construct()`). `spec_objects_operational/manifest.yaml` + declares no `construct:` for any type, on `origin/main`, on the PR head, or + on any remote branch. For all eight types (configuration, migration, sli, + slo, alert, runbook, incident, deployment), `shape()` therefore takes its + "object type with no declaration keeps the record" path. No + `min_clauses` / `identity_field_required` / `occurrence_field_required` / + `min_operations` rule applies, so the relaxation does not let `quire validate` + pass a document that FCD lowering then refuses. Consistent for every type, + no finding. If a construct is added later with one of those rules, the + matching locator must become `required: true` at the same time. +- With quire 0.54.0, `runbook-no-operations` still fails with its + `at operations: [] has less than 1 item` detail, and the deleted + `migration-no-invariants` fixture no longer yields `semantic.record-invalid`. + +## Verdict + +**CONDITIONAL** — no high finding. Two mediums (stale schema descriptions, +TC-092 asserting different cases than its ACs) and one low ceremony item. + +## Findings + +| ID | Severity | Summary | Refs | Escape Cause | +|---|---|---|---|---| +| FND-001 | medium | The TypeSpec doc comments, which the emitter copies into each shipped schema's `description`, still state the removed rule: Migration "`clauses` is required because…", Slo "`clauses` is required because…", Alert "`clauses` is required and carries the condition", Runbook "`operations` is required". The file header (line 12, "type-specific required keys") and line 20 / 256 / 455 ("the only model that requires…") also describe a required set that no longer exists. Shipped `Migration.json`, `Slo.json`, `Alert.json`, `Runbook.json` now contradict their own `required`-free bodies. | typespec/main.tsp:12, typespec/main.tsp:291, typespec/main.tsp:352, typespec/main.tsp:383, typespec/main.tsp:401 | wrong-requirement | +| FND-002 | medium | TC-092 does not assert what its two tagged ACs say. FR-006-AC-2 names "an `Incident` without an occurrence field", but the test sends `{"fields": [OCCURRENCE]}` — an occurrence field with no identity — so it fails on the identity rule, not the occurrence rule. FR-006-AC-1's "a record lacking `fields`, `clauses` or `operations` validates" half is never exercised in TC-092: it only checks `schema.get("required")` is falsy; the validating calls live in TC-041..049 tagged to FR-004. | tests/test_role_schemas.py:488-501 | correct-requirement-no-evidence | +| FND-003 | low | Ceremony: `assert len(fixtures) >= 9` is a file count. It does not prove the nine named cases exist (any nine files pass), and the real checks — `seen == expected_codes` and the unique-`detail` assertion — already carry the value. The PR re-tuned the number from 10 to 9 instead of removing it. | tests/test_skeletons_semantic.py:155 | wrong-requirement | diff --git a/reviews/plat-277-soo-pr29-gap-analysis.md b/reviews/plat-277-soo-pr29-gap-analysis.md new file mode 100644 index 0000000..9f7a0ca --- /dev/null +++ b/reviews/plat-277-soo-pr29-gap-analysis.md @@ -0,0 +1,32 @@ +--- +id: SR-103 +title: "Gap analysis — spec-objects-operational PR #29 (PLAT-277 F1 optional record keys)" +type: SpecReview +analysis: gap-analysis +scope: "agent-ix/spec-objects-operational; spec/functional/FR-006-optional-sections-optional-keys.md, spec/functional/FR-004-role-schemas.md, spec/tests.md, tests/test_role_schemas.py" +review_set: subset +--- +# Gap analysis — spec-objects-operational PR #29 (PLAT-277 F1) + +## Summary + +Ticket: PLAT-277 (finding F1). Planless; plan completion: not assessed. +`quoin matrix --repo . --json` (quoin 0.29.1) on the PR head: FR-006-AC-1 and +FR-006-AC-2 are tagged (both by +`test_a_record_lacking_an_optional_section_key_validates_and_the_key_stays_checked`); +FR-004-AC-10 is tagged by the renamed empty-record test; FR-004-CON-2 is gone +from spec and matrix. FR-006-CON-1 is untagged. No production code in the +diff lacks an owning requirement: the TypeSpec change is owned by FR-006 and +the regenerated schemas by FR-002. + +## Verdict + +**CONDITIONAL** — one medium (an untagged constraint that `spec/tests.md` +reports as covered), one low (no document-level evidence for the F1 outcome). + +## Findings + +| ID | Severity | Summary | Refs | Escape Cause | +|---|---|---|---|---| +| FND-001 | medium | FR-006-CON-1 is `untagged` in the computed matrix, yet `spec/tests.md` maps it to TC-092 and marks FR-006 ✅. The constraint also restates FR-006-AC-1's first half ("no shipped object-type schema lists a required key"), so either tag it or delete the redundant constraint. | spec/functional/FR-006-optional-sections-optional-keys.md:51, spec/tests.md:75, spec/tests.md:146 | correct-requirement-no-evidence | +| FND-002 | low | F1 is a document-level defect (a document without the optional section was refused as `semantic.record-invalid`), but every FR-006 test runs on hand-built records. Nothing asserts that `validate_document` accepts a document lacking `## Invariants` / `## Operations` / `## Properties`. Reviewer checked by hand with quire 0.54.0: a runbook without `## Operations` and the deleted migration fixture produce no `semantic.record-invalid`. The deleted fixture could have become that positive check. | tests/fixtures/negative/migration-no-invariants.md, tests/test_role_schemas.py:488 | correct-requirement-no-evidence | diff --git a/reviews/plat-277-soo-pr29-spec-review.md b/reviews/plat-277-soo-pr29-spec-review.md new file mode 100644 index 0000000..700605d --- /dev/null +++ b/reviews/plat-277-soo-pr29-spec-review.md @@ -0,0 +1,37 @@ +--- +id: SR-104 +title: "Spec review — spec-objects-operational PR #29 (PLAT-277 F1 optional record keys)" +type: SpecReview +analysis: base +scope: "agent-ix/spec-objects-operational; spec/functional/FR-004-role-schemas.md, spec/functional/FR-005-executable-skeletons.md, spec/functional/FR-006-optional-sections-optional-keys.md, spec/tests.md, spec/spec.md" +review_set: subset +--- +# Spec review — spec-objects-operational PR #29 (PLAT-277 F1) + +## Summary + +Ticket: PLAT-277 (finding F1). Examined new FR-006 (statement, Behavior, +FR-006-CON-1, FR-006-AC-1, FR-006-AC-2), TC-092, the FR-004 table rows, +FR-004-AC-2..5, AC-9, AC-10, the removal of FR-004-CON-2, the FR-005 +negative-fixture list, FR-005-AC-5 and the tests.md rows TC-041..049, TC-064. + +FR-006's statement is a sound, testable rule and matches the manifest: every +`properties` / `invariants` / `operations` locator for all eight types is +`required: false`. Its Behavior keeps item rules on present keys and leaves +locators unchanged, and the diff honours both. Removing FR-004-CON-2 is +correct; it is not left dangling in tests or matrix. `quire validate` on the +three FRs is clean; `spec/tests.md` fails only on the pre-existing +`Coverage Status` column name, unchanged by this PR. + +## Verdict + +**CONDITIONAL** — no high finding. Two mediums: FR-005 and the FR-004 table +still describe a required set that FR-006 abolished. One low wording drift. + +## Findings + +| ID | Severity | Summary | Refs | Escape Cause | +|---|---|---|---|---| +| FND-001 | medium | FR-005 still keys obligations on "types that require `fields`" / "require `operations`". Line 49 (which skeletons author `## Properties`), line 61 (which author `## Operations`) and FR-005-AC-4 ("`fields` `available` for the six types that require `fields`") now denote the empty set, so read literally they impose nothing. The PR updated the Invariants bullet (line 58) but not these. The same wording is in plan Task-005 line 46. Restate them as "the six types that admit `fields`" / "the types whose skeleton authors `operations`". | spec/functional/FR-005-executable-skeletons.md:49, spec/functional/FR-005-executable-skeletons.md:61, spec/functional/FR-005-executable-skeletons.md:91 | wrong-requirement | +| FND-002 | medium | In the FR-004 table, every row now reads Required keys "none (FR-006)", but `fields` / `clauses` / `operations` were not added to the Optional keys column. The table no longer lists the full key set each type admits; for example Deployment's row omits `fields` and `operations`. The prose still says "`Deployment` requires an identity field" (line 61) and "`Incident` is the only model that requires occurrence identity" (lines 65, 100). Under FR-006 those hold only when `fields` is present, and the spec does not say so. Two readers could disagree on whether an `Incident` with no `## Properties` must be refused. | spec/functional/FR-004-role-schemas.md:61, spec/functional/FR-004-role-schemas.md:65, spec/functional/FR-004-role-schemas.md:70-77, spec/functional/FR-004-role-schemas.md:100 | wrong-requirement | +| FND-003 | low | AC/TC wording drift. TC-041, TC-045, TC-046 and TC-047 (and their tests) now assert that an absent key validates, but FR-004-AC-2, AC-6, AC-7 and AC-8 do not say so. FR-004-AC-4 gained "a record without `fields` validates", but the TC-043 row did not. Plan.md line 157 still says "the ten named cases". | spec/functional/FR-004-role-schemas.md:122-128, spec/tests.md:118-122 | wrong-requirement | diff --git a/spec/functional/FR-004-role-schemas.md b/spec/functional/FR-004-role-schemas.md index d7aefa7..ed66f02 100644 --- a/spec/functional/FR-004-role-schemas.md +++ b/spec/functional/FR-004-role-schemas.md @@ -65,16 +65,16 @@ occurrence field: a deployment declaration says what the release *is*, and model that requires occurrence identity, and the only model that admits an occurrence field at all. -| Object type | Model | Required keys | Optional keys | Item rules | +| Object type | Model | Required keys | Optional keys | Item rules (each on `fields`, `clauses` or `operations` applies only when that key is present) | |---|---|---|---|---| -| configuration | `Configuration` | none (FR-006) | `scopes: ScopeAssignment[]`, `configures: SemanticId[]`, `clauses`, `operations` | `fields` has ≥ 1 item, 0 identity fields (a parameter set is keyed by the configured object, not by itself) and 0 occurrence fields; `relations` forbidden | -| migration | `Migration` | none (FR-006) | `rollback: RollbackDecl`, `migrates: SemanticId[]`, `dependsOn: SemanticId[]`, `operations` | `fields` has ≥ 1 item, 0 identity fields and 0 occurrence fields (an `applied_at` row is execution state); `clauses` has ≥ 1 item — a migration declares the safety condition it preserves; `relations` forbidden | -| sli | `Sli` | none (FR-006) | `measures: SemanticId[]`, `clauses` | `fields` has ≥ 1 item, ≥ 1 measured field and 0 occurrence fields; `operations` forbidden — an SLI declares a measurement, not behaviour | -| slo | `Slo` | none (FR-006) | `objective: ObjectiveDecl`, `constrains: SemanticId[]`, `dependsOn: SemanticId[]` | `fields` has ≥ 1 item, ≥ 1 measured field and 0 occurrence fields; `clauses` has ≥ 1 item — the objective is an invariant over the SLI; `operations` forbidden | -| alert | `Alert` | none (FR-006) | `conditions: AlertCondition[]`, `escalatesTo: SemanticId[]`, `references: SemanticId[]`, `operations` | `clauses` has ≥ 1 item — an alert is a firing condition; `fields` forbidden | -| runbook | `Runbook` | none (FR-006) | `steps: RunbookStep[]`, `remediates: SemanticId[]`, `clauses` | `operations` has ≥ 1 item — a runbook declares the actions an operator performs; `fields` forbidden | -| incident | `Incident` | none (FR-006) | `evidence: EvidenceRef[]`, `correlates: SemanticId[]`, `breaches: SemanticId[]`, `triggers: SemanticId[]`, `clauses`, `operations` | `fields` has ≥ 1 item, ≥ 1 identity field, and ≥ 1 occurrence field — an incident is an observed occurrence and is the only type that is | -| deployment | `Deployment` | none (FR-006) | `rollout: RolloutDecl`, `deploys: SemanticId[]`, `dependsOn: SemanticId[]`, `relations`, `clauses` | `fields` has ≥ 1 item, ≥ 1 identity field (the release identity) and 0 occurrence fields; `operations` has ≥ 1 item (the lifecycle actions) | +| configuration | `Configuration` | none (FR-006) | `fields`, `scopes: ScopeAssignment[]`, `configures: SemanticId[]`, `clauses`, `operations` | `fields` has ≥ 1 item, 0 identity fields (a parameter set is keyed by the configured object, not by itself) and 0 occurrence fields; `relations` forbidden | +| migration | `Migration` | none (FR-006) | `fields`, `clauses`, `rollback: RollbackDecl`, `migrates: SemanticId[]`, `dependsOn: SemanticId[]`, `operations` | `fields` has ≥ 1 item, 0 identity fields and 0 occurrence fields (an `applied_at` row is execution state); `clauses` has ≥ 1 item — a migration declares the safety condition it preserves; `relations` forbidden | +| sli | `Sli` | none (FR-006) | `fields`, `measures: SemanticId[]`, `clauses` | `fields` has ≥ 1 item, ≥ 1 measured field and 0 occurrence fields; `operations` forbidden — an SLI declares a measurement, not behaviour | +| slo | `Slo` | none (FR-006) | `fields`, `clauses`, `objective: ObjectiveDecl`, `constrains: SemanticId[]`, `dependsOn: SemanticId[]` | `fields` has ≥ 1 item, ≥ 1 measured field and 0 occurrence fields; `clauses` has ≥ 1 item — the objective is an invariant over the SLI; `operations` forbidden | +| alert | `Alert` | none (FR-006) | `clauses`, `conditions: AlertCondition[]`, `escalatesTo: SemanticId[]`, `references: SemanticId[]`, `operations` | `clauses` has ≥ 1 item — an alert is a firing condition; `fields` forbidden | +| runbook | `Runbook` | none (FR-006) | `operations`, `steps: RunbookStep[]`, `remediates: SemanticId[]`, `clauses` | `operations` has ≥ 1 item — a runbook declares the actions an operator performs; `fields` forbidden | +| incident | `Incident` | none (FR-006) | `fields`, `evidence: EvidenceRef[]`, `correlates: SemanticId[]`, `breaches: SemanticId[]`, `triggers: SemanticId[]`, `clauses`, `operations` | `fields` has ≥ 1 item, ≥ 1 identity field, and ≥ 1 occurrence field — an incident is an observed occurrence and is the only type that is | +| deployment | `Deployment` | none (FR-006) | `fields`, `operations`, `rollout: RolloutDecl`, `deploys: SemanticId[]`, `dependsOn: SemanticId[]`, `relations`, `clauses` | `fields` has ≥ 1 item, ≥ 1 identity field (the release identity) and 0 occurrence fields; `operations` has ≥ 1 item (the lifecycle actions) | - `ScopeAssignment` SHALL be `{ parameter: Identifier, scope: ConfigurationScope }` with `ConfigurationScope` the closed set `creation`, `runtime`, `session` — the same vocabulary the `configuration-scope` lint rule allows on the untyped `## Configuration` table. - `RollbackDecl` SHALL be `{ strategy: RollbackStrategy, clause?: ClauseRef, doc?: string }` with `RollbackStrategy` the closed set `reversible`, `forward_only`, `compensating`. @@ -119,13 +119,13 @@ occurrence field at all. | ID | Criteria | Verification | |----|----------|--------------| | FR-004-AC-1 | Each of the eight shipped object-type schemas differs from every other in at least one required, forbidden, or item rule listed in the table; a schema with only `type: object` is absent. | Test | -| FR-004-AC-2 | A configuration record with one non-identity field validates against `Configuration.json`, with `scopes` accepted when present; the same record with an identity field fails; a record with an empty `fields` array fails. | Test | +| FR-004-AC-2 | A configuration record with one non-identity field validates against `Configuration.json`, with `scopes` accepted when present; the same record with an identity field fails; a record without `fields` validates ([FR-006](./FR-006-optional-sections-optional-keys.md)); a record with an empty `fields` array fails. | Test | | FR-004-AC-3 | A migration record with one non-identity field and one clause validates against `Migration.json`, with `rollback` accepted when present; the same record without `clauses` validates ([FR-006](./FR-006-optional-sections-optional-keys.md)); a record with an identity field fails. | Test | | FR-004-AC-4 | An SLI record whose field carries a `type.unit` validates against `Sli.json`; the same record with the unit removed fails; a record without `fields` validates; a record carrying `operations` fails. | Test | | FR-004-AC-5 | An SLO record with a measured field and one clause validates against `Slo.json`, with `objective` accepted when present; the same record without `clauses` validates ([FR-006](./FR-006-optional-sections-optional-keys.md)); a record carrying `operations` fails. | Test | -| FR-004-AC-6 | An alert record with one clause validates against `Alert.json`, with `conditions` accepted when present; a record carrying `fields` fails; a record with an empty `clauses` array fails. | Test | -| FR-004-AC-7 | A runbook record with one operation validates against `Runbook.json`, with `steps` accepted when present; a record carrying `fields` fails; a record with an empty `operations` array fails. | Test | -| FR-004-AC-8 | An incident record with an identity field and a `Timestamp` field validates against `Incident.json`, with `evidence` accepted when present; the same record without the `Timestamp` field fails; the same record without the identity field fails. | Test | +| FR-004-AC-6 | An alert record with one clause validates against `Alert.json`, with `conditions` accepted when present; a record without `clauses` validates ([FR-006](./FR-006-optional-sections-optional-keys.md)); a record carrying `fields` fails; a record with an empty `clauses` array fails. | Test | +| FR-004-AC-7 | A runbook record with one operation validates against `Runbook.json`, with `steps` accepted when present; a record without `operations` validates ([FR-006](./FR-006-optional-sections-optional-keys.md)); a record carrying `fields` fails; a record with an empty `operations` array fails. | Test | +| FR-004-AC-8 | An incident record with an identity field and a `Timestamp` field validates against `Incident.json`, with `evidence` accepted when present; the same record without the `Timestamp` field fails; the same record without the identity field fails; a record without `fields` validates ([FR-006](./FR-006-optional-sections-optional-keys.md)). | Test | | FR-004-AC-9 | A deployment record with an identity field and one operation validates against `Deployment.json`, with `rollout` accepted when present; the same record without `operations` validates ([FR-006](./FR-006-optional-sections-optional-keys.md)); the same record with the identity flag removed fails. | Test | | FR-004-AC-10 | The empty record `{}` validates against all eight object-type schemas ([FR-006](./FR-006-optional-sections-optional-keys.md)), and a record carrying an `observations` key fails every one of them. The second half holds for any unknown key, so it is evidence of the seal only; the type-specific purity evidence is FR-004-AC-14. | Test | | FR-004-AC-11 | `evidence` is declared by `Incident.json` and by no other shipped schema; an `evidence` entry whose `record` falls outside quoin FR-059's `$defs/identity` pattern fails, one carrying an `ix://` identity (also a valid FR-059 `record_id`) validates, and one whose `shape` is outside `EvidenceRecordShape` fails. | Test | diff --git a/spec/functional/FR-005-executable-skeletons.md b/spec/functional/FR-005-executable-skeletons.md index 0ba2567..bedbaf3 100644 --- a/spec/functional/FR-005-executable-skeletons.md +++ b/spec/functional/FR-005-executable-skeletons.md @@ -46,7 +46,7 @@ refuse. ## Behavior -- Each skeleton whose type requires `fields` (`configuration`, `migration`, `sli`, `slo`, `incident`, `deployment`) SHALL author `## Properties` as one table with the header exactly `Field | Type | Multiplicity | Constraints`. +- Each skeleton whose type declares `fields` (`configuration`, `migration`, `sli`, `slo`, `incident`, `deployment`) SHALL author `## Properties` as one table with the header exactly `Field | Type | Multiplicity | Constraints`. - The `alert` and `runbook` skeletons SHALL carry no `## Properties` section, because `Alert` and `Runbook` forbid `fields`. - The `sli` and `slo` skeletons SHALL each carry at least one `## Properties` row whose `Type` cell has a trailing bracketed unit (for example `Decimal(5,4) [1]` or `Duration [ms]`), so the extracted record carries the measured field `Sli`/`Slo` require. - The `incident` skeleton SHALL carry one `identity` row and one `Timestamp` row, so the extracted record carries the identity and occurrence fields `Incident` requires. @@ -88,7 +88,7 @@ refuse. | FR-005-AC-1 | Every skeleton file (eight types plus three alternates) passes `validate_document` against this module with `is_valid` true and no `semantic.record-invalid` error. | Test | | FR-005-AC-2 | For `configuration`, `sli`, and `deployment`, the table and `sysml` skeletons extract to identical normalized `fields` with `fieldsForm` `table` and `fence` respectively. | Test | | FR-005-AC-3 | Under a bundle index built from the skeleton frontmatter, every skeleton extracts with zero `error` diagnostics and zero `semantic.unresolved-type` findings, and every non-kernel `type.target` starts with `ix://agent-ix/spec-objects-operational/type/`. | Test | -| FR-005-AC-4 | Each skeleton's `availability` states match its type: `fields` `available` for the six types that require `fields` and `not_applicable` for `alert` and `runbook`; `operations` `available` for `runbook` and `deployment`; `clauses` `available` for every skeleton. | Test | +| FR-005-AC-4 | Each skeleton's `availability` states match its type: `fields` `available` for the six types that declare `fields` and `not_applicable` for `alert` and `runbook`; `operations` `available` for `runbook` and `deployment`; `clauses` `available` for every skeleton. | Test | | FR-005-AC-5 | Every negative fixture fails validation with an error message containing both its `expect:` code and its `detail:` substring, and at least the nine cases listed in Behavior are present. | Test | | FR-005-AC-6 | Every skeleton's H2 set equals a subset of the headings the manifest asserts for its type and includes every `required: true` heading. | Test | | FR-005-AC-7 | The skeleton for each of the eight types has no placeholder token and every asserted section body is non-empty. | Test | diff --git a/spec/functional/FR-006-optional-sections-optional-keys.md b/spec/functional/FR-006-optional-sections-optional-keys.md index 43b019b..b5b020d 100644 --- a/spec/functional/FR-006-optional-sections-optional-keys.md +++ b/spec/functional/FR-006-optional-sections-optional-keys.md @@ -38,18 +38,13 @@ so that a document satisfying every mandatory locator is not refused as - The absence of `fields`, `clauses` or `operations` is a valid declaration, not a defect. - Locators stay as they are: no section is made mandatory by this requirement. - -## Constraints - -| ID | Constraint | Type | Validation | -|----|------------|------|------------| -| FR-006-CON-1 | A schema SHALL require a key only where a required manifest locator feeds it; no operational record key has one. | Integrity | Test | +- This manifest declares no `construct:` for any type. If one is added later and requires a member, that member's locator SHALL become `required: true` in the same change and its schema key required again. ## Acceptance Criteria | ID | Criteria | Verification | |----|----------|--------------| -| FR-006-AC-1 | No shipped object-type schema lists a required key, and a record lacking `fields`, `clauses` or `operations` validates against each type that declares the key. | Test | +| FR-006-AC-1 | No shipped object-type schema lists a required key; a record lacking `fields`, `clauses` or `operations` validates against each type that declares the key, and a skeleton with its `## Properties`, `## Invariants` or `## Operations` section removed validates. | Test | | FR-006-AC-2 | A present key is still checked: an empty `fields`, `clauses` or `operations` array, an `Slo` field without a unit, an `Incident` without an occurrence field, or a `Deployment` with an empty `operations` array fails. | Test | ## Dependencies diff --git a/spec/tests.md b/spec/tests.md index fabd439..4bf2a33 100644 --- a/spec/tests.md +++ b/spec/tests.md @@ -72,7 +72,7 @@ those fail when the engine is absent (FR-005-AC-10). | FR-003 | FR-003-AC-1..8, FR-003-CON-1..3 | TC-030..TC-038 | ✅ AC-5 is a Demonstration; AC-6's naming half is an expected failure | | FR-004 | FR-004-AC-1..15, FR-004-CON-1, FR-004-CON-3..5 | TC-040..TC-054 | ✅ AC-15's refusal half is an expected failure on quoin#335 | | FR-005 | FR-005-AC-1..11, FR-005-CON-1..2 | TC-060..TC-072 | ✅ | -| FR-006 | FR-006-AC-1..2, FR-006-CON-1 | TC-092 | ✅ | +| FR-006 | FR-006-AC-1..2 | TC-092 | ✅ | ### Integration Test Coverage @@ -117,7 +117,7 @@ those fail when the engine is absent (FR-005-AC-10). | TC-040 | Each of the eight schemas differs from every other in a required, forbidden, or item rule; none is `type: object` only | Unit | P0 | FR-004-AC-1 | ✅ | | TC-041 | Configuration: non-identity record validates and accepts `scopes`; an identity field fails; no `fields` validates (FR-006); empty `fields` fails | Integration | P0 | FR-004-AC-2 | ✅ | | TC-042 | Migration: non-identity record with one clause validates and accepts `rollback`; no `clauses` validates (FR-006); an identity field fails | Integration | P0 | FR-004-AC-3 | ✅ | -| TC-043 | SLI: a unit-bearing field validates; the unit removed fails; `operations` fails | Integration | P0 | FR-004-AC-4 | ✅ | +| TC-043 | SLI: a unit-bearing field validates; the unit removed fails; no `fields` validates (FR-006); `operations` fails | Integration | P0 | FR-004-AC-4 | ✅ | | TC-044 | SLO: a unit-bearing field with one clause validates and accepts `objective`; no `clauses` validates (FR-006); `operations` fails | Integration | P0 | FR-004-AC-5 | ✅ | | TC-045 | Alert: one clause validates and accepts `conditions`; no `clauses` validates (FR-006); `fields` fails; empty `clauses` fails | Integration | P0 | FR-004-AC-6 | ✅ | | TC-046 | Runbook: one operation validates and accepts `steps`; no `operations` validates (FR-006); `fields` fails; empty `operations` fails | Integration | P0 | FR-004-AC-7 | ✅ | @@ -143,7 +143,7 @@ those fail when the engine is absent (FR-005-AC-10). | TC-071 | With the Quire wheel absent, every semantic test fails naming `extract_semantic` and `poetry install`; none skips | Integration | P0 | FR-005-AC-10 | ✅ | | TC-072 | `pyproject.toml` declares `quire` as a dev dependency pinned to the `internal-pypi` source | Unit | P1 | FR-005-AC-11 | ✅ | | TC-091 | Quoin install roundtrip: record, install, list, derive, restore | Manual | P1 | IT-002-SC-01, IT-002-SC-02, IT-002-SC-03, IT-002-SC-04, IT-002-SC-05, IT-002-SC-06 | 🚧 the Quoin build is now available; the row waits on the operator opt-in | -| TC-092 | A record lacking the optional section key validates against all eight schemas; a present key is still checked by its item rules | Unit | P0 | FR-006-AC-1, FR-006-AC-2, FR-006-CON-1 | ✅ | +| TC-092 | A record lacking the optional section key validates against all eight schemas; a present key is still checked by its item rules | Unit | P0 | FR-006-AC-1, FR-006-AC-2 | ✅ | ## Test Environment diff --git a/spec_objects_operational/schemas/Alert.json b/spec_objects_operational/schemas/Alert.json index cae5ea9..4ee2297 100644 --- a/spec_objects_operational/schemas/Alert.json +++ b/spec_objects_operational/schemas/Alert.json @@ -38,5 +38,5 @@ "unevaluatedProperties": { "not": {} }, - "description": "An alert: a firing condition over an indicator.\n\n`fields` is forbidden by the seal — an alert declares a condition, not data.\n`clauses` is required and carries the condition; `conditions` carries the\nsame condition in typed form once the extractor populates it." + "description": "An alert: a firing condition over an indicator.\n\n`fields` is forbidden by the seal — an alert declares a condition, not data.\n`clauses` is optional and carries the condition when present; `conditions` carries the\nsame condition in typed form once the extractor populates it." } diff --git a/spec_objects_operational/schemas/Configuration.json b/spec_objects_operational/schemas/Configuration.json index d801094..d12e60a 100644 --- a/spec_objects_operational/schemas/Configuration.json +++ b/spec_objects_operational/schemas/Configuration.json @@ -43,7 +43,7 @@ "unevaluatedProperties": { "not": {} }, - "description": "Seals the standing definitions against an occurrence row.\n\nThe seal (`...Record`) refuses an *observation key*; it says nothing\nabout a `fields` row. Without this rule a `Migration` could declare\n`applied_at : Timestamp` and a `Deployment` a `deployed_at : Timestamp`, and\nthe type would be an observed execution wearing a standing definition's\nschema. `Incident` is the only model that admits an occurrence field, and it\nrequires one. JSON Schema admits one `contains` per array, so this second\npredicate rides an `allOf` clause; `minContains: 0` is required because the\nkeyword defaults to 1 and would otherwise contradict `maxContains: 0`.A configuration: the tunable parameters of a configurable object. A\nparameter set is keyed by the object it configures, not by itself, so it\ncarries no identity field. `relations` is forbidden by the seal.", + "description": "Seals the standing definitions against an occurrence row.\n\nThe seal (`...Record`) refuses an *observation key*; it says nothing\nabout a `fields` row. Without this rule a `Migration` could declare\n`applied_at : Timestamp` and a `Deployment` a `deployed_at : Timestamp`, and\nthe type would be an observed execution wearing a standing definition's\nschema. `Incident` is the only model that admits an occurrence field, and it\ndemands one when `fields` is present. JSON Schema admits one `contains` per array, so this second\npredicate rides an `allOf` clause; `minContains: 0` is required because the\nkeyword defaults to 1 and would otherwise contradict `maxContains: 0`.A configuration: the tunable parameters of a configurable object. A\nparameter set is keyed by the object it configures, not by itself, so it\ncarries no identity field. `relations` is forbidden by the seal.", "allOf": [ { "properties": { diff --git a/spec_objects_operational/schemas/Incident.json b/spec_objects_operational/schemas/Incident.json index a15e933..44724cb 100644 --- a/spec_objects_operational/schemas/Incident.json +++ b/spec_objects_operational/schemas/Incident.json @@ -53,7 +53,7 @@ "unevaluatedProperties": { "not": {} }, - "description": "An incident: something that happened.\n\nThis is the module's one observed-execution type and the only model that\nrequires an occurrence identity — at least one identity field (which\nincident it was) and at least one `Timestamp` field (when it was). The\nsecond `contains` predicate is expressed through `allOf`, because JSON\nSchema admits one `contains` per array.\n\n`Incident` is also the only model that declares `evidence`, which is what\nmakes the `agent-ix/quoin#267` mapping canonical: exactly one key on exactly\none type, referencing that family's records by `SemanticId` and copying none\nof their fields.", + "description": "An incident: something that happened.\n\nThis is the module's one observed-execution type and the only model that\ndemands an occurrence identity when `fields` is present — at least one identity field (which\nincident it was) and at least one `Timestamp` field (when it was). The\nsecond `contains` predicate is expressed through `allOf`, because JSON\nSchema admits one `contains` per array.\n\n`Incident` is also the only model that declares `evidence`, which is what\nmakes the `agent-ix/quoin#267` mapping canonical: exactly one key on exactly\none type, referencing that family's records by `SemanticId` and copying none\nof their fields.", "allOf": [ { "properties": { diff --git a/spec_objects_operational/schemas/Migration.json b/spec_objects_operational/schemas/Migration.json index af8a5b3..116ad2d 100644 --- a/spec_objects_operational/schemas/Migration.json +++ b/spec_objects_operational/schemas/Migration.json @@ -47,7 +47,7 @@ "unevaluatedProperties": { "not": {} }, - "description": "A migration: a versioned change and the safety condition it preserves.\n\n`clauses` is required because a migration that states no safety condition\nstates nothing a reviewer can check. The declaration carries rollback\n*intent* (`rollback`) and never execution state: no applied-at timestamp, no\nrow count, no database status. A consumer needing execution state reads it\nthrough `migrates` or through an `Incident` that references the migration.\n`relations` is forbidden by the seal.", + "description": "A migration: a versioned change and the safety condition it preserves.\n\n`clauses` is optional; a migration that states no safety condition\nstates nothing a reviewer can check, so when present it needs one clause. The declaration carries rollback\n*intent* (`rollback`) and never execution state: no applied-at timestamp, no\nrow count, no database status. A consumer needing execution state reads it\nthrough `migrates` or through an `Incident` that references the migration.\n`relations` is forbidden by the seal.", "allOf": [ { "properties": { diff --git a/spec_objects_operational/schemas/Runbook.json b/spec_objects_operational/schemas/Runbook.json index a70ed7f..6dfa348 100644 --- a/spec_objects_operational/schemas/Runbook.json +++ b/spec_objects_operational/schemas/Runbook.json @@ -32,5 +32,5 @@ "unevaluatedProperties": { "not": {} }, - "description": "A runbook: the operations an operator performs to remediate something.\n\n`fields` is forbidden by the seal — a runbook declares actions, not data.\n`operations` is required; `steps` orders them once the extractor populates\nit." + "description": "A runbook: the operations an operator performs to remediate something.\n\n`fields` is forbidden by the seal — a runbook declares actions, not data.\n`operations` is optional; `steps` orders them once the extractor populates\nit." } diff --git a/spec_objects_operational/schemas/Slo.json b/spec_objects_operational/schemas/Slo.json index e0052e9..f1d0cd2 100644 --- a/spec_objects_operational/schemas/Slo.json +++ b/spec_objects_operational/schemas/Slo.json @@ -39,7 +39,7 @@ "unevaluatedProperties": { "not": {} }, - "description": "A service level objective: the promise made over an SLI.\n\n`clauses` is required because the objective is an invariant over the\nindicator, expressed as a clause; `objective` carries the same promise in\ntyped form once the extractor populates it. `operations` is forbidden by the\nseal, and so is every consumed-budget or sample key.", + "description": "A service level objective: the promise made over an SLI.\n\n`clauses` is optional; the objective is an invariant over the\nindicator, expressed as a clause when present; `objective` carries the same promise in\ntyped form once the extractor populates it. `operations` is forbidden by the\nseal, and so is every consumed-budget or sample key.", "allOf": [ { "properties": { diff --git a/tests/test_role_schemas.py b/tests/test_role_schemas.py index 9b4cab3..7a84b6c 100644 --- a/tests/test_role_schemas.py +++ b/tests/test_role_schemas.py @@ -492,10 +492,14 @@ def test_a_record_lacking_an_optional_section_key_validates_and_the_key_stays_ch """Hand-built: the record a document without the optional section yields.""" for name in OBJECT_TYPES: assert not schema_of(name).get("required"), name + assert ok(schema_registry(MODEL_OF[name]), {}), name + identity = field("incident_id", "UUID", identity=True) assert not ok(schema_registry("Configuration"), {"fields": []}) assert not ok(schema_registry("Migration"), {"clauses": []}) assert not ok(schema_registry("Slo"), {"fields": [field("ratio", "Decimal")]}) assert not ok(schema_registry("Alert"), {"clauses": []}) assert not ok(schema_registry("Runbook"), {"operations": []}) - assert not ok(schema_registry("Incident"), {"fields": [OCCURRENCE]}) + # An identity field alone fails for the missing occurrence field. + assert not ok(schema_registry("Incident"), {"fields": [identity]}) + assert ok(schema_registry("Incident"), {"fields": [identity, OCCURRENCE]}) assert not ok(schema_registry("Deployment"), {"operations": []}) diff --git a/tests/test_skeletons_semantic.py b/tests/test_skeletons_semantic.py index 3edaafa..321d450 100644 --- a/tests/test_skeletons_semantic.py +++ b/tests/test_skeletons_semantic.py @@ -152,7 +152,6 @@ def test_every_negative_fixture_fails_for_its_own_reason(quire_engine): code alone does not tell them apart: each fixture also names a `detail:` substring no other fixture's message carries, and both are asserted.""" fixtures = sorted(NEGATIVE_DIR.glob("*.md")) - assert len(fixtures) >= 9, "the nine named negative cases are not all present" expected_codes = { "semantic.record-invalid", "semantic.properties-both-forms", @@ -305,3 +304,33 @@ def test_a_properties_section_with_both_forms_is_refused(quire_engine): assert any( "semantic.properties-both-forms" in e["message"] for e in result["errors"] ) + + +#: Skeleton -> the optional section whose removal must still validate (FR-006). +OPTIONAL_SECTION_REMOVED = ( + ("configuration", "Properties"), + ("sli", "Properties"), + ("incident", "Properties"), + ("migration", "Invariants"), + ("slo", "Invariants"), + ("alert", "Invariants"), + ("runbook", "Operations"), + ("deployment", "Operations"), +) + + +@pytest.mark.trace("TC-092", "FR-006-AC-1") +@pytest.mark.parametrize(("name", "heading"), OPTIONAL_SECTION_REMOVED) +def test_a_document_without_the_optional_section_is_not_record_invalid( + quire_engine, name, heading +): + """The F1 outcome: the extractor omits the key for an absent section, so + the document draws no `semantic.record-invalid` for it.""" + text = (SKELETONS_DIR / f"{name}.md").read_text() + cut = re.sub(rf"(?ms)^## {heading}\n.*?(?=^## |\Z)", "", text) + assert cut != text + result = quire_engine.validate_document(name, str(PACKAGE_ROOT), cut) + refusals = [ + e["message"] for e in result["errors"] if "record-invalid" in e["message"] + ] + assert not refusals, refusals diff --git a/typespec/main.tsp b/typespec/main.tsp index 40cf218..7e575db 100644 --- a/typespec/main.tsp +++ b/typespec/main.tsp @@ -9,16 +9,16 @@ using AgentIx.Semantic.Core; * * One model per operational object type this module contributes, each validating * that type's Quire declaration record (fields, relations, clauses, - * operations; quire-rs FR-070..FR-072) with type-specific required keys, - * forbidden keys, and item rules (FR-004). Every grammar item is a `$ref` to + * operations; quire-rs FR-070..FR-072) with type-specific forbidden keys and item + * rules, and no required key (FR-004, FR-006). Every grammar item is a `$ref` to * `@agent-ix/semantic-core` and is never redeclared here (FR-004-CON-1); * this namespace contributes archetype shapes only. * * The module's central distinction (FR-004): `Configuration`, `Migration`, * `Sli`, `Slo`, `Alert`, `Runbook`, and `Deployment` are *standing definitions* * — what a system is configured to do, promises, and how it is remediated. - * `Incident` is the one *observed execution*, and the only model that requires - * an occurrence identity or declares `evidence`. Every model is sealed + * `Incident` is the one *observed execution*, and the only model that + * demands an occurrence identity or declares `evidence`. Every model is sealed * (`...Record`), so no type can carry an accumulated observation, a * measured sample, a consumed error budget, or an applied-migration timestamp; * those live in the `agent-ix/quoin#267` evidence record family, which @@ -253,7 +253,7 @@ model EvidenceRef { * `applied_at : Timestamp` and a `Deployment` a `deployed_at : Timestamp`, and * the type would be an observed execution wearing a standing definition's * schema. `Incident` is the only model that admits an occurrence field, and it - * requires one. JSON Schema admits one `contains` per array, so this second + * demands one when `fields` is present. JSON Schema admits one `contains` per array, so this second * predicate rides an `allOf` clause; `minContains: 0` is required because the * keyword defaults to 1 and would otherwise contradict `maxContains: 0`. */ @@ -288,8 +288,8 @@ model Configuration { /** * A migration: a versioned change and the safety condition it preserves. * - * `clauses` is required because a migration that states no safety condition - * states nothing a reviewer can check. The declaration carries rollback + * `clauses` is optional; a migration that states no safety condition + * states nothing a reviewer can check, so when present it needs one clause. The declaration carries rollback * *intent* (`rollback`) and never execution state: no applied-at timestamp, no * row count, no database status. A consumer needing execution state reads it * through `migrates` or through an `Incident` that references the migration. @@ -349,8 +349,8 @@ model Sli { /** * A service level objective: the promise made over an SLI. * - * `clauses` is required because the objective is an invariant over the - * indicator, expressed as a clause; `objective` carries the same promise in + * `clauses` is optional; the objective is an invariant over the + * indicator, expressed as a clause when present; `objective` carries the same promise in * typed form once the extractor populates it. `operations` is forbidden by the * seal, and so is every consumed-budget or sample key. */ @@ -380,7 +380,7 @@ model Slo { * An alert: a firing condition over an indicator. * * `fields` is forbidden by the seal — an alert declares a condition, not data. - * `clauses` is required and carries the condition; `conditions` carries the + * `clauses` is optional and carries the condition when present; `conditions` carries the * same condition in typed form once the extractor populates it. */ model Alert { @@ -398,7 +398,7 @@ model Alert { * A runbook: the operations an operator performs to remediate something. * * `fields` is forbidden by the seal — a runbook declares actions, not data. - * `operations` is required; `steps` orders them once the extractor populates + * `operations` is optional; `steps` orders them once the extractor populates * it. */ model Runbook { @@ -452,7 +452,7 @@ model Deployment { * An incident: something that happened. * * This is the module's one observed-execution type and the only model that - * requires an occurrence identity — at least one identity field (which + * demands an occurrence identity when `fields` is present — at least one identity field (which * incident it was) and at least one `Timestamp` field (when it was). The * second `contains` predicate is expressed through `allOf`, because JSON * Schema admits one `contains` per array. From d74cd82818f1a4cdb8c274c791c0bd2bd6c6bd7a Mon Sep 17 00:00:00 2001 From: Agent IX Date: Mon, 9 Nov 2026 09:44:57 -0800 Subject: [PATCH 3/4] PLAT-277: FR-005 says declares, not requires; dispositioned reviews Co-Authored-By: Claude Sonnet 5.5 --- reviews/plat-277-soo-pr29-code-review.md | 15 +++++++++++++++ reviews/plat-277-soo-pr29-gap-analysis.md | 10 ++++++++++ reviews/plat-277-soo-pr29-spec-review.md | 10 ++++++++++ spec/functional/FR-005-executable-skeletons.md | 4 ++-- 4 files changed, 37 insertions(+), 2 deletions(-) diff --git a/reviews/plat-277-soo-pr29-code-review.md b/reviews/plat-277-soo-pr29-code-review.md index 8a23b4f..57b1612 100644 --- a/reviews/plat-277-soo-pr29-code-review.md +++ b/reviews/plat-277-soo-pr29-code-review.md @@ -62,3 +62,18 @@ TC-092 asserting different cases than its ACs) and one low ceremony item. | FND-001 | medium | The TypeSpec doc comments, which the emitter copies into each shipped schema's `description`, still state the removed rule: Migration "`clauses` is required because…", Slo "`clauses` is required because…", Alert "`clauses` is required and carries the condition", Runbook "`operations` is required". The file header (line 12, "type-specific required keys") and line 20 / 256 / 455 ("the only model that requires…") also describe a required set that no longer exists. Shipped `Migration.json`, `Slo.json`, `Alert.json`, `Runbook.json` now contradict their own `required`-free bodies. | typespec/main.tsp:12, typespec/main.tsp:291, typespec/main.tsp:352, typespec/main.tsp:383, typespec/main.tsp:401 | wrong-requirement | | FND-002 | medium | TC-092 does not assert what its two tagged ACs say. FR-006-AC-2 names "an `Incident` without an occurrence field", but the test sends `{"fields": [OCCURRENCE]}` — an occurrence field with no identity — so it fails on the identity rule, not the occurrence rule. FR-006-AC-1's "a record lacking `fields`, `clauses` or `operations` validates" half is never exercised in TC-092: it only checks `schema.get("required")` is falsy; the validating calls live in TC-041..049 tagged to FR-004. | tests/test_role_schemas.py:488-501 | correct-requirement-no-evidence | | FND-003 | low | Ceremony: `assert len(fixtures) >= 9` is a file count. It does not prove the nine named cases exist (any nine files pass), and the real checks — `seen == expected_codes` and the unique-`detail` assertion — already carry the value. The PR re-tuned the number from 10 to 9 instead of removing it. | tests/test_skeletons_semantic.py:155 | wrong-requirement | + +## Dispositions + +Round 1, fix commit e2ca621. Re-verified against the real pinned +`@agent-ix/semantic-core@0.3.2`: `schemas-check` passes (27 match) and a +full regenerate leaves the tree clean. With quire 0.54.0, the PR head gives +153 passed / 6 failed and origin/main 144 / 6. The failing set is the same +6 tests, and their errors are identical apart from a one-line shift in +`test_skeletons_semantic.py`. + +| FND | outcome | reason | +|---|---|---| +| FND-001 | fixed | Doc comments in `typespec/main.tsp` (header, L20, L256, Migration, Slo, Alert, Runbook, Incident) now say optional / "when present"; the six affected schema descriptions were regenerated by the emitter. | +| FND-002 | fixed | TC-092 now asserts `{}` validates for all eight types and uses an identity-only Incident record, which fails for the missing occurrence field. Eight parametrized `validate_document` cases tagged TC-092 / FR-006-AC-1 remove the optional section from each skeleton. | +| FND-003 | fixed | `assert len(fixtures) >= 9` deleted. | diff --git a/reviews/plat-277-soo-pr29-gap-analysis.md b/reviews/plat-277-soo-pr29-gap-analysis.md index 9f7a0ca..8d2895f 100644 --- a/reviews/plat-277-soo-pr29-gap-analysis.md +++ b/reviews/plat-277-soo-pr29-gap-analysis.md @@ -30,3 +30,13 @@ reports as covered), one low (no document-level evidence for the F1 outcome). |---|---|---|---|---| | FND-001 | medium | FR-006-CON-1 is `untagged` in the computed matrix, yet `spec/tests.md` maps it to TC-092 and marks FR-006 ✅. The constraint also restates FR-006-AC-1's first half ("no shipped object-type schema lists a required key"), so either tag it or delete the redundant constraint. | spec/functional/FR-006-optional-sections-optional-keys.md:51, spec/tests.md:75, spec/tests.md:146 | correct-requirement-no-evidence | | FND-002 | low | F1 is a document-level defect (a document without the optional section was refused as `semantic.record-invalid`), but every FR-006 test runs on hand-built records. Nothing asserts that `validate_document` accepts a document lacking `## Invariants` / `## Operations` / `## Properties`. Reviewer checked by hand with quire 0.54.0: a runbook without `## Operations` and the deleted migration fixture produce no `semantic.record-invalid`. The deleted fixture could have become that positive check. | tests/fixtures/negative/migration-no-invariants.md, tests/test_role_schemas.py:488 | correct-requirement-no-evidence | + +## Dispositions + +Round 1, fix commit e2ca621. `quoin matrix` reports no untagged criterion: +FR-006-AC-1 is tagged by 2 binders and FR-006-AC-2 by 1. + +| FND | outcome | reason | +|---|---|---| +| FND-001 | fixed | FR-006-CON-1 deleted from FR-006 and from both `spec/tests.md` rows. | +| FND-002 | fixed | `test_a_document_without_the_optional_section_is_not_record_invalid` runs `validate_document` on each of the eight skeletons with its optional section removed; all 8 pass with quire 0.54.0. | diff --git a/reviews/plat-277-soo-pr29-spec-review.md b/reviews/plat-277-soo-pr29-spec-review.md index 700605d..0607350 100644 --- a/reviews/plat-277-soo-pr29-spec-review.md +++ b/reviews/plat-277-soo-pr29-spec-review.md @@ -35,3 +35,13 @@ still describe a required set that FR-006 abolished. One low wording drift. | FND-001 | medium | FR-005 still keys obligations on "types that require `fields`" / "require `operations`". Line 49 (which skeletons author `## Properties`), line 61 (which author `## Operations`) and FR-005-AC-4 ("`fields` `available` for the six types that require `fields`") now denote the empty set, so read literally they impose nothing. The PR updated the Invariants bullet (line 58) but not these. The same wording is in plan Task-005 line 46. Restate them as "the six types that admit `fields`" / "the types whose skeleton authors `operations`". | spec/functional/FR-005-executable-skeletons.md:49, spec/functional/FR-005-executable-skeletons.md:61, spec/functional/FR-005-executable-skeletons.md:91 | wrong-requirement | | FND-002 | medium | In the FR-004 table, every row now reads Required keys "none (FR-006)", but `fields` / `clauses` / `operations` were not added to the Optional keys column. The table no longer lists the full key set each type admits; for example Deployment's row omits `fields` and `operations`. The prose still says "`Deployment` requires an identity field" (line 61) and "`Incident` is the only model that requires occurrence identity" (lines 65, 100). Under FR-006 those hold only when `fields` is present, and the spec does not say so. Two readers could disagree on whether an `Incident` with no `## Properties` must be refused. | spec/functional/FR-004-role-schemas.md:61, spec/functional/FR-004-role-schemas.md:65, spec/functional/FR-004-role-schemas.md:70-77, spec/functional/FR-004-role-schemas.md:100 | wrong-requirement | | FND-003 | low | AC/TC wording drift. TC-041, TC-045, TC-046 and TC-047 (and their tests) now assert that an absent key validates, but FR-004-AC-2, AC-6, AC-7 and AC-8 do not say so. FR-004-AC-4 gained "a record without `fields` validates", but the TC-043 row did not. Plan.md line 157 still says "the ten named cases". | spec/functional/FR-004-role-schemas.md:122-128, spec/tests.md:118-122 | wrong-requirement | + +## Dispositions + +Round 1, fix commit e2ca621. + +| FND | outcome | reason | +|---|---|---| +| FND-001 | still-open | FR-005 L49, FR-005-AC-4 and Task-005 L46 now say "declares `fields`", but FR-005 L61 still reads "Each skeleton whose type requires `operations` (`runbook`, `deployment`)", which is the empty set after FR-006. One-word fix: "declares `operations`". | +| FND-002 | fixed | The Optional keys column now lists `fields` / `clauses` / `operations` for every admitting type. The Item rules header now states that each rule applies only when its key is present, and FR-004-AC-8 states that an Incident without `fields` validates. | +| FND-003 | fixed | FR-004-AC-2, AC-6, AC-7 and AC-8 now state that an absent key validates, the TC-043 row gained "no `fields` validates", and plan.md drops "ten". | diff --git a/spec/functional/FR-005-executable-skeletons.md b/spec/functional/FR-005-executable-skeletons.md index bedbaf3..753620b 100644 --- a/spec/functional/FR-005-executable-skeletons.md +++ b/spec/functional/FR-005-executable-skeletons.md @@ -49,7 +49,7 @@ refuse. - Each skeleton whose type declares `fields` (`configuration`, `migration`, `sli`, `slo`, `incident`, `deployment`) SHALL author `## Properties` as one table with the header exactly `Field | Type | Multiplicity | Constraints`. - The `alert` and `runbook` skeletons SHALL carry no `## Properties` section, because `Alert` and `Runbook` forbid `fields`. - The `sli` and `slo` skeletons SHALL each carry at least one `## Properties` row whose `Type` cell has a trailing bracketed unit (for example `Decimal(5,4) [1]` or `Duration [ms]`), so the extracted record carries the measured field `Sli`/`Slo` require. -- The `incident` skeleton SHALL carry one `identity` row and one `Timestamp` row, so the extracted record carries the identity and occurrence fields `Incident` requires. +- The `incident` skeleton SHALL carry one `identity` row and one `Timestamp` row, so the extracted record carries the identity and occurrence fields `Incident` demands when `fields` is present. - The `configuration` and `migration` skeletons SHALL carry no `identity` row, because `Configuration` and `Migration` admit zero identity fields. - The `configuration`, `sli`, and `deployment` alternate skeletons SHALL author the same declarations as one ```` ```sysml ```` fence of `attribute : [] { }` and `ref item : []` lines. - Each alternate skeleton SHALL declare the same fields as its table skeleton, under that skeleton's frontmatter `id` and `title`; the module therefore ships two files under one id by intent, and the identity of their extracted `FieldDecl[]` is the obligation FR-005-AC-2 tests. @@ -58,7 +58,7 @@ refuse. - Every skeleton SHALL author `## Invariants` with one `### ` per clause, each owning exactly one ```` ```ocl ```` fence, because every object-type model of [FR-004](./FR-004-role-schemas.md) admits `clauses`; none requires one ([FR-006](./FR-006-optional-sections-optional-keys.md)). - Each skeleton's frontmatter SHALL carry `object: ` beside `type: `, because Quire runs the semantic layer (extraction and record validation) on the `object:` archetype of a document; a skeleton without it validates its headings only. - The manifest SHALL gain a `required: false` `section_body` locator for every `## Properties`, `## Invariants`, and `## Operations` section a skeleton introduces, so the section is asserted by the manifest and remains optional for existing artifacts. -- Each skeleton whose type requires `operations` (`runbook`, `deployment`) SHALL author `## Operations` with one `### ` per operation, an optional `| Param | Type | Multiplicity | Constraints |` table, a `Returns:` line where the operation returns a value, and optional `Pre:`/`Post:` lines that, when present, name clause ids declared in the same artifact. +- Each skeleton whose type declares `operations` (`runbook`, `deployment`) SHALL author `## Operations` with one `### ` per operation, an optional `| Param | Type | Multiplicity | Constraints |` table, a `Returns:` line where the operation returns a value, and optional `Pre:`/`Post:` lines that, when present, name clause ids declared in the same artifact. - Every skeleton `title` SHALL be an `Identifier` (`^[A-Za-z_][A-Za-z0-9_]*$`), distinct across all skeletons and outside the `KernelScalar` names, so a `Type` cell can name it. - Every `Type` cell that names another skeleton SHALL use that skeleton's `title`, so that under a bundle index built from the skeletons every non-kernel token resolves to `ix://agent-ix/spec-objects-operational/type/` with no `semantic.unresolved-type` finding. - Every skeleton SHALL keep every H2 heading whose manifest locator is `required: true` for its type. From 17012c85c991b79ce3007353b02ceead8a8a81db Mon Sep 17 00:00:00 2001 From: Agent IX <agent@agent-ix.dev> Date: Mon, 9 Nov 2026 09:46:19 -0800 Subject: [PATCH 4/4] PLAT-277: round-2 disposition row in spec review Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> --- reviews/plat-277-soo-pr29-spec-review.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/reviews/plat-277-soo-pr29-spec-review.md b/reviews/plat-277-soo-pr29-spec-review.md index 0607350..2a18c29 100644 --- a/reviews/plat-277-soo-pr29-spec-review.md +++ b/reviews/plat-277-soo-pr29-spec-review.md @@ -45,3 +45,9 @@ Round 1, fix commit e2ca621. | FND-001 | still-open | FR-005 L49, FR-005-AC-4 and Task-005 L46 now say "declares `fields`", but FR-005 L61 still reads "Each skeleton whose type requires `operations` (`runbook`, `deployment`)", which is the empty set after FR-006. One-word fix: "declares `operations`". | | FND-002 | fixed | The Optional keys column now lists `fields` / `clauses` / `operations` for every admitting type. The Item rules header now states that each rule applies only when its key is present, and FR-004-AC-8 states that an Incident without `fields` validates. | | FND-003 | fixed | FR-004-AC-2, AC-6, AC-7 and AC-8 now state that an absent key validates, the TC-043 row gained "no `fields` validates", and plan.md drops "ten". | + +Round 2, head d74cd82. + +| FND | outcome | reason | +|---|---|---| +| FND-001 | fixed | FR-005 L61 now reads "Each skeleton whose type declares `operations`", and L52 now reads "`Incident` demands when `fields` is present". A scan of spec/, plan/ and typespec/ for "require(s) `fields`/`operations`/`clauses`", "types that require" and "whose type requires" finds nothing left. |