Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion plan/Plan-001-semantic-data-schemas/plan.md
Original file line number Diff line number Diff line change
Expand Up @@ -122,7 +122,7 @@ hard failure — a skip that was hiding a broken locator lookup for `configurati
- [x] **TC-022** (FR-002-CON-4): `package-lock.json` resolves every package from npmjs except `@agent-ix/semantic-core`.
- [x] **TC-023** (FR-002-AC-2): no test hard-codes the `$id` version segment.
- [x] **TC-027** (FR-002-AC-13): `make install` provisions the TypeSpec toolchain.
- [x] **TC-030** (FR-003-AC-1, FR-003-CON-1): the `semantic` block equals the nine admitted keys and `exports` equals the eight object-type names.
- [x] **TC-030** (FR-003-AC-1, FR-003-CON-1): the `semantic` block equals the eight admitted keys and `exports` equals the eight object-type names.
- [x] **TC-031** (FR-003-AC-2): every exported type's `data_schema` is the reference form and the referenced file hashes to the recorded digest.
- [x] **TC-032** (FR-003-AC-3): every 0.2.0 locator is unchanged against the checked-in baseline.
- [x] **TC-033** (FR-003-CON-2): every locator added after 0.2.0 is `required: false`.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ lexicon definitions issue #5 records as truncated.

## Subtasks

- [x] **`semantic` block.** Exactly the nine admitted keys: `contract_version: 1.0.0`, `semantic_core: 0.1.0`, `package: agent-ix/spec-objects-operational`, `exports` (the eight object-type names), `imports: {}`, `targets: [json-schema, markdown]`, `mappings: [typed-table, sysml-fence, ocl-clause]`, `compatibility_posture: additive`, `legacy_forms: warning`.
- [x] **`semantic` block.** Exactly the eight admitted keys: `contract_version: 1.0.0`, `package: agent-ix/spec-objects-operational`, `exports` (the eight object-type names), `imports: {}`, `targets: [json-schema, markdown]`, `mappings: [typed-table, sysml-fence, ocl-clause]`, `compatibility_posture: additive`, `legacy_forms: warning`.
- [x] **Reference-form `data_schema`.** `{ schema: schemas/<Model>.json, digest: sha256:<hex> }` on every exported type, the digest written by the generator over the shipped bytes. No inline `data_schema` survives.
- [x] **Version.** `version: 0.3.0`, bumped together with the `@jsonSchema` base in one commit.
- [x] **Locator and lint-rule preservation.** Every 0.2.0 locator keeps its `from`, heading, `language`, `required`, `multiple` and `assert` facets, compared structurally against the checked-in baseline from Task-007; the `configuration-scope` rule keeps its three allowed values and `warning` severity.
Expand Down
11 changes: 5 additions & 6 deletions scripts/generate-schemas.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -50,14 +50,13 @@ function requireNode() {
}

/**
* The semantic-core base this module extends: the one version the manifest
* declares as `semantic.semantic_core`, read without a YAML parser so the file
* is never reserialized.
* The semantic-core base this module extends: the exact `@agent-ix/semantic-core`
* version pinned in `package.json`, the version the schemas are compiled against.
*/
function semanticCoreBase() {
const manifest = readFileSync(resolve(packageDir, "manifest.yaml"), "utf8");
const declared = manifest.match(/^[ ]{2}semantic_core:[ ]*([^\s#]+)[ ]*$/m)?.[1];
if (!declared) fail("manifest.yaml declares no semantic.semantic_core");
const pkg = JSON.parse(readFileSync(resolve(repoRoot, "package.json"), "utf8"));
const declared = pkg.devDependencies?.["@agent-ix/semantic-core"];
if (!declared) fail("package.json pins no @agent-ix/semantic-core devDependency");
return `https://schemas.agent-ix.org/semantic-core/${declared}/`;
}

Expand Down
4 changes: 2 additions & 2 deletions spec/functional/FR-002-emitted-json-schemas.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,13 +46,13 @@ fails the build.
- `make install` SHALL install the TypeSpec toolchain with `npm ci` alongside the Python dependencies, so `make lint` — which runs `make schemas-check` — has the compiler and emitter it needs; without it the drift gate fails for a missing toolchain rather than for drift.
- `make schemas` SHALL run `node scripts/generate-schemas.mjs`.
- The generator SHALL compile `typespec/` with `tsp compile`, keep only the emitted files whose `$id` starts with the module base, and discard the re-emitted semantic-core files.
- If the emitter leaves any `$id` or `$ref` relative, then the generator SHALL rewrite it to `<base><file>` (module models) or `https://schemas.agent-ix.org/semantic-core/<declared version>/<file>` (semantic-core models), where `<declared version>` is the `semantic.semantic_core` the manifest declares.
- If the emitter leaves any `$id` or `$ref` relative, then the generator SHALL rewrite it to `<base><file>` (module models) or `https://schemas.agent-ix.org/semantic-core/<declared version>/<file>` (semantic-core models), where `<declared version>` is the exact `@agent-ix/semantic-core` version pinned in `package.json`.
- When no `$id` or `$ref` is relative, the generator SHALL record the normalization as `applied: false`.
- If `tsp compile` fails or emits no module model, then the generator SHALL exit non-zero without touching the committed output.
- If `node` is older than 20 or `tsp` is not resolvable, then the generator SHALL exit non-zero naming the required Node version or the missing binary.
- In `--check` mode the generator SHALL write no file, neither under `spec_objects_operational/schemas/` nor in `manifest.yaml`.
- Every emitted schema SHALL declare `$schema: https://json-schema.org/draft/2020-12/schema` and `$id: https://schemas.agent-ix.org/agent-ix/spec-objects-operational/<Model>.json`.
- Every `$ref` in an emitted schema SHALL name either a sibling `https://schemas.agent-ix.org/agent-ix/spec-objects-operational/<File>.json` that ships in `schemas/`, or `https://schemas.agent-ix.org/semantic-core/<declared version>/<Model>.json` (the version `semantic.semantic_core` declares).
- Every `$ref` in an emitted schema SHALL name either a sibling `https://schemas.agent-ix.org/agent-ix/spec-objects-operational/<File>.json` that ships in `schemas/`, or `https://schemas.agent-ix.org/semantic-core/<declared version>/<Model>.json` (the version pinned in `package.json`).
- `make schemas-check` SHALL run the generator with `--check`.
- `make lint` SHALL run `make schemas-check`, so a `typespec/` edit that was never regenerated fails before push rather than at review.
- If any emitted file differs from the committed output, a committed file under `spec_objects_operational/schemas/` is stale (it has no emitted counterpart in this run), then the check SHALL exit non-zero naming each such file.
Expand Down
4 changes: 2 additions & 2 deletions spec/functional/FR-003-semantic-manifest-contract.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ lexicon entry keeps its meaning.

## Behavior

- The manifest `semantic` block SHALL carry exactly these keys and values: `contract_version: 1.0.0`, `semantic_core` (the one semantic-core version the module declares it extends), `package: agent-ix/spec-objects-operational`, `exports` listing every object type that ships a schema, `imports: {}`, `targets: [json-schema, markdown]`, `mappings: [typed-table, sysml-fence, ocl-clause]`, `compatibility_posture: additive`, `legacy_forms: warning`.
- The manifest `semantic` block SHALL carry exactly these keys and values: `contract_version: 1.0.0`, `package: agent-ix/spec-objects-operational`, `exports` listing every object type that ships a schema, `imports: {}`, `targets: [json-schema, markdown]`, `mappings: [typed-table, sysml-fence, ocl-clause]`, `compatibility_posture: additive`, `legacy_forms: warning`.
- `semantic.exports` SHALL name all eight object types: `configuration`, `migration`, `sli`, `slo`, `alert`, `runbook`, `incident`, `deployment`.
- No exported object type SHALL carry an inline `data_schema`.
- The `configuration_table` locator (`table_row` under `Configuration`, asserting the columns `Name | Scope | Type | Default | Description`) SHALL stay in place, so the untyped configuration table continues to be yielded beside the semantic record.
Expand All @@ -58,7 +58,7 @@ lexicon entry keeps its meaning.

| ID | Criteria | Verification |
|----|----------|--------------|
| FR-003-AC-1 | The loaded `semantic` block equals the nine admitted keys with the values above, and `exports` equals the eight object-type names. | Test |
| FR-003-AC-1 | The loaded `semantic` block equals the eight admitted keys with the values above, and `exports` equals the eight object-type names. | Test |
| FR-003-AC-3 | The `id`, `title` and `type` frontmatter locators and each object type's defining locators are `required: true`. | Test |
| FR-003-AC-4 | `quire.Registry.load_from([module dir])` lists all eight archetypes and `validate_document` on each skeleton reports no `semantic.*` load failure. | Test |
| FR-003-AC-5 | `quoin module install path:<module dir>` exits zero and `quoin module` lists `spec-objects-operational`; the previously installed entry is restored afterwards. | Demonstration |
Expand Down
2 changes: 1 addition & 1 deletion spec/tests.md
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,7 @@ those fail when the engine is absent (FR-005-AC-10).
| TC-026 | `.gitattributes` marks `*.json`, `*.tsp`, `*.yaml` and `*.md` `eol=lf` | Unit | P2 | FR-002-AC-12 | ✅ |
| TC-027 | `make install` provisions the TypeSpec toolchain, so `make lint`'s drift gate fails for drift and not for a missing compiler | Unit | P1 | FR-002-AC-13 | ✅ |
| TC-028 | `stage-npm.mjs --clean` removes every staged root path and leaves the inner package sources byte-identical | Integration | P1 | FR-002-AC-14 | ✅ |
| TC-030 | The `semantic` block equals the nine admitted keys and `exports` equals the eight types | Unit | P0 | FR-003-AC-1, FR-003-CON-1 | ✅ |
| TC-030 | The `semantic` block equals the eight admitted keys and `exports` equals the eight types | Unit | P0 | FR-003-AC-1, FR-003-CON-1 | ✅ |
| TC-032 | The core frontmatter locators and each type's defining locators are required | Unit | P0 | FR-003-AC-3 | ✅ |
| TC-034 | `quire.Registry.load_from` lists all eight archetypes and `validate_document` on every skeleton reports no `semantic.*` load failure | Integration | P0 | FR-003-AC-4 | ✅ |
| TC-035 | An unknown `semantic` key is refused by the loader; the refusal names the key or path | Integration | P1 | FR-003-AC-6 | ✅ the naming half is an expected failure on quire-rs#221 |
Expand Down
1 change: 0 additions & 1 deletion spec_objects_operational/manifest.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,6 @@ version: 0.3.0
description: 'Filament Module: tier-2 operational ObjectTypes (configuration, migration, sli, slo, alert, runbook, incident, deployment)'
semantic:
contract_version: 1.0.0
semantic_core: 0.3.2
package: agent-ix/spec-objects-operational
exports:
- configuration
Expand Down
6 changes: 4 additions & 2 deletions tests/conftest.py
Original file line number Diff line number Diff line change
Expand Up @@ -104,9 +104,12 @@ def load_manifest() -> dict[str, Any]:


MODULE_BASE = "https://schemas.agent-ix.org/agent-ix/spec-objects-operational/"
SEMANTIC_CORE_VERSION = json.loads((REPO_ROOT / "package.json").read_text())[
"devDependencies"
]["@agent-ix/semantic-core"]
SEMANTIC_CORE_BASE = (
"https://schemas.agent-ix.org/semantic-core/"
f"{load_manifest()['semantic']['semantic_core']}/"
f"{SEMANTIC_CORE_VERSION}/"
)


Expand Down Expand Up @@ -162,7 +165,6 @@ def semantic_module(semantic_block: dict[str, Any]) -> dict[str, Any]:
"""The `module` block `extract_semantic` takes, derived from the manifest."""
return {
"contractVersion": semantic_block["contract_version"],
"semanticCore": semantic_block["semantic_core"],
"package": semantic_block["package"],
"exports": semantic_block["exports"],
"imports": semantic_block["imports"],
Expand Down
3 changes: 1 addition & 2 deletions tests/test_manifest_semantic.py
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,6 @@

ADMITTED_KEYS = {
"contract_version",
"semantic_core",
"package",
"exports",
"imports",
Expand Down Expand Up @@ -53,7 +52,7 @@ def module_copy(tmp_path, mutate=None):


@pytest.mark.trace("TC-030", "FR-003-AC-1", "FR-003-CON-1")
def test_the_semantic_block_carries_the_nine_admitted_keys_and_eight_exports(
def test_the_semantic_block_carries_the_eight_admitted_keys_and_eight_exports(
semantic_block,
):
assert set(semantic_block) == ADMITTED_KEYS
Expand Down
Loading