@agentshouse/mdmodel 0.1.0-alpha.8 → 0.1.0-c68e2039f1ca8

package/fixtures/README.md

@@ -2,10 +2,13 @@
 
 Each directory under `cases/` is one text Library, one validation context,
 and one expected verdict. Consumers load the files under `library/` as
-path-to-content, load the required `context.json` as `ValidationContext`, and
-compare `validate(library, context)` against `expected.json`. Text-only cases
-carry `{ "binaryTargets": [] }`. Binary targets are membership declarations;
-the corpus supplies no binary bytes or placeholder Documents.
+path-to-content, an absent `library/` being the empty Library, and the
+required `context.json` as `ValidationContext`. Cases with a `schema.yaml` call
+`verify` with its text, then compare its refusal or
+`validate(library, context, verified.model)` against `expected.json`. Other
+cases compare `validate(library, context)` directly. Text-only cases carry
+`{ "binaryTargets": [] }`. Binary targets are membership declarations; the
+corpus supplies no binary bytes or placeholder Documents.
 
 ## Preamble operations
 
@@ -15,29 +18,52 @@ the validation Libraries. Each row carries `name`, exact `source`, expected
 the source, compare `Document.preamble`, apply
 `{ kind: 'preamble', prior: preamble, value }`, and compare the serialized result.
 These cases cover empty and heading-free Documents, frontmatter boundaries,
-fenced headings, newline/source preservation, and the Runtime moved-export
-example from its [approved candidate](https://github.com/agentshouse/mdruntime/blob/ed0a6f0b95317d9ade846ec1f2871a3997519bc4/test/rooms.ts).
-The package check runs every row in ESM, CommonJS, and the browser-target VM
-bundle, also checking stale priors, immutable Documents, and conversion of the
-Runtime link rewrite into a preamble operation through public APIs.
+fenced headings, newline/source preservation, and a moved-export link rewrite.
 
 ## Projection
 
 `projection.json` exercises the public `project` seam separately from the
-validation Libraries. It carries `definitions`, the MD Type definition sources
-keyed by a label, and `cases`. Each case carries `name`, the `file` the Document
-sits at, exact `source`, the `documentTargets` the collection holds as Markdown
-documents, the `definition` label or `null`, an optional `move`, and `expected`.
+validation Libraries. It carries `schema`, one schema text, and `cases`. Each
+case carries `name`, the `file` the Document sits at, exact `source`, the
+`documentTargets` the collection holds as Markdown documents, the `definition`
+type name or `null`, an optional `move`, an optional `links` inventory, an
+optional `relabel`, an optional `filtered`, and `expected`.
 A case carrying a `move` lists both the Path its target sits at and the Path the
 move takes it to, because the collection holds that target either way.
 
-Parse the source, call `project(document, file, context)` with
-`{ documentTargets, definition }`, and compare against `expected`, replacing the
-`<package-version>` token in a refusal the same way `cases/` does. Then check
+Verify the schema, parse the source, call `project(document, file, context)`
+with `documentTargets` and the verified type `definition` names, and compare against `expected`. Where
+`links` is present, compare `links(document, file)` against it. Then check
 that the source is unchanged. Where `move` is present, apply
 `{ kind: 'link', href, to }`, confirm the serialized Document changed, and
 confirm the projection of the moved Document is still exactly `expected`: a
-moved Path rewrites destinations and leaves the projection alone.
+moved Path rewrites destinations and leaves the projection alone. Where
+`relabel` is present, split the source at its `from`, which the source carries
+exactly once, join the pieces with its `to`, parse the result, and confirm its
+projection is exactly the relabel's own `expected` and differs from the case's:
+a changed visible label changes the projection. Where `filtered` is present,
+apply `{ kind: 'field', name: field, value, prior }` with its `field` and
+`value` and the Document's current value as `prior`, confirm the serialized
+Document changed, and confirm its projection is still exactly `expected`: a
+change to a value that is not prose leaves the projection alone.
+
+## Division
+
+`division.json` exercises the public `divide` seam separately from the
+validation Libraries. It carries `schema` and `cases` like `projection.json`,
+and each case adds the `budget` the division runs under. Parse the source, call
+`divide(document, file, context)` with `{ documentTargets, definition, budget }`,
+and compare against `expected`: either `{ "ok": true, "spans": [...] }`, where
+each span carries the exact `text` to embed and the exact `source` the returned
+`start` and `end` address in that case's source, or `{ "ok": false, "refusal": ... }`. Then
+check that the source is unchanged. A span's `text` and `source` differ where
+the embedded text repeats a continuation's own heading, carries an internal
+link's visible label, or carries a frontmatter value without the quotes the
+author wrote, and where the addressed extent encloses a declared structured
+section between two pieces one span packs together or the whole of a free-text
+value one span carries part of. `start` and `end` are UTF-8 byte offsets into the case's
+source; every source in this corpus is ASCII, so a consumer compares the
+addressed `source` with an ordinary string slice.
 
 ## Verdict format
 
@@ -53,53 +79,57 @@ Refusal:
 {
   "verdict": "refuse",
   "file": "<library path>",
-  "location": "<field or section name>",
+  "location": "<JSON Pointer or section name>",
   "rule": "<rule id>",
-  "version": "<package version>",
   "referrers": ["<library path>"]
 }
 ```
 
-`location` is omitted when the rule is not about a field or section.
-`referrers` is present only for `referenced-missing-file`.
-The `version` field in these fixtures is the token `<package-version>`;
-replace it with the package's semantic version before comparing.
+`location` is the JSON Pointer of the frontmatter value a rule concerns, such
+as `/shipping/city`, or the name of the section it concerns, and is omitted when
+the rule concerns neither. `referrers` is present only for
+`referenced-missing-file`. A schema refusal carries no `file`; its `location`
+is the JSON Pointer of the schema part it concerns, such as
+`/task/properties/title/type`, or `line <n>` for `schema-yaml`.
 
 ## Rule ids
 
-| Rule                      | When                                                                   |
-| ------------------------- | ---------------------------------------------------------------------- |
-| `binary-target-document`  | A path is declared as both a text Document and a binary target         |
-| `frontmatter-fence`       | A present frontmatter fence does not parse as the accepted YAML subset |
-| `definition-type`         | A `types/` file is not a definition, or its type name is empty         |
-| `definition-shape`        | A definition carries a key other than `type`, `fields`, and `sections` |
-| `definition-fields`       | `fields` is not a mapping                                              |
-| `definition-field`        | A field spec is not an object of the accepted keys                     |
-| `definition-field-kind`   | A field kind is not string, number, date, enum, reference, or list     |
-| `definition-enum-values`  | An enum field has no non-empty string `values`                         |
-| `definition-reference-to` | A reference field has no non-empty `to` type name                      |
-| `definition-list-of`      | A list field has no `of` that is one scalar kind                       |
-| `definition-sections`     | `sections` is not a mapping                                            |
-| `definition-section`      | A section spec is not an object of the accepted keys                   |
-| `definition-section-kind` | A section kind is not `text` or `list`                                 |
-| `definition-duplicate`    | Two definition files share a type name                                 |
-| `unknown-type`            | A file declares a type that is not in `types/`                         |
-| `required-field`          | A required field is missing                                            |
-| `required-section`        | A required section heading is missing                                  |
-| `field-kind`              | A field value fails its kind, including date                           |
-| `field-enum`              | A field value is not one of the declared enum values                   |
-| `unresolved-reference`    | A reference does not resolve to a current file of the required type    |
-| `unresolved-link`         | A relative body link does not resolve to a current path                |
-| `structured-section`      | A declared structured-list section does not parse as a list            |
-| `referenced-missing-file` | Remaining files still reference an absent path                         |
-| `unwritable-link`         | No Markdown destination form can carry a new link destination          |
-
-`unwritable-link` is refused by `apply`, not by `validate`, so no case under
-`cases/` carries it.
+A frontmatter value that fails a JSON Schema keyword is refused under that
+keyword's name, such as `required`, `type`, `enum`, `format`, `pattern`,
+`minimum`, `maxLength`, `maxItems` or `oneOf`, at the value's JSON Pointer; a
+missing required key is named by the Pointer it would sit at. A malformed
+schema keyword is refused under that keyword's name at its Pointer in the
+schema text. The model's own rules:
+
+| Rule                      | When                                                                              |
+| ------------------------- | --------------------------------------------------------------------------------- |
+| `binary-target-document`  | A path is declared as both a text Document and a binary target                    |
+| `frontmatter-fence`       | A present frontmatter fence does not parse as the accepted YAML subset            |
+| `schema-yaml`             | A schema text is not a mapping in the accepted YAML subset                        |
+| `schema-type-name`        | A type name is empty, starts with `$`, or is `any` or `attachment`                |
+| `schema`                  | A type or subschema is neither a mapping nor a boolean                            |
+| `schema-keyword`          | A schema carries a key that is no JSON Schema 2020-12 keyword the model admits    |
+| `$defs`                   | `$defs` is not a mapping                                                          |
+| `$ref`                    | A `$ref` reaches no subschema under `#/$defs/` of the same file                   |
+| `reference`               | `reference` is not on a string or names something but a type, `any`, `attachment` |
+| `sections`                | A section is not `{ kind: text }` or `{ kind: list, items }` over one scalar      |
+| `member_document`         | The mark is not a boolean, or a second type carries it                            |
+| `unknown-type`            | A file declares a type absent from the governing schema                           |
+| `undeclared-field`        | A closed object carries a key it does not declare                                 |
+| `required-section`        | A required section heading is missing                                             |
+| `unresolved-reference`    | A reference field, list item or section item reaches no file of a type it names   |
+| `unresolved-link`         | A relative body link does not resolve to a current path                           |
+| `structured-section`      | A declared list section is not a list of values of its item schema                |
+| `referenced-missing-file` | Remaining files still reference an absent path                                    |
+| `unwritable-link`         | No Markdown destination form can carry a new link destination                     |
+| `division-budget`         | A division budget is not a whole number of at least 2                             |
+
+`unwritable-link` is refused by `apply` and `division-budget` by `divide`, not
+by `validate`, so no case under `cases/` carries either.
 
 ## YAML subset
 
-Frontmatter is a mapping in a closed YAML subset: block and flow mappings,
-block and flow sequences, plain and quoted scalars, `true`, `false`, `null`,
+Frontmatter and a schema text are each a mapping in a closed YAML subset: block and flow mappings,
+block and flow sequences, a block sequence item that opens a mapping, plain and quoted scalars, `true`, `false`, `null`,
 and decimal numbers. It does not take YAML 1.1 boolean or timestamp aliases,
-octal numbers, anchors, tags, or block scalars.
+octal numbers, anchors, tags, or block scalars. A mapping carries each key once.

package/fixtures/cases/absent-optional-field/library/companies/acme.md

@@ -0,0 +1,4 @@
+---
+type: company
+name: Acme
+---

package/fixtures/cases/absent-optional-field/library/deals/lead.md

@@ -0,0 +1,6 @@
+---
+type: deal
+title: Lead
+company: ../companies/acme.md
+stage: lead
+---

package/fixtures/cases/absent-optional-field/schema.yaml

@@ -0,0 +1,56 @@
+$defs:
+  address:
+    type: object
+    properties:
+      city: { type: string }
+      country: { type: string, pattern: '^[A-Z]{2}$' }
+    required: [city]
+company:
+  properties:
+    name: { type: string }
+deal:
+  type: object
+  properties:
+    title: { type: string, minLength: 1, maxLength: 40 }
+    company: { type: string, reference: company }
+    stage: { enum: [lead, proposal, won, lost], default: lead }
+    amount: { type: integer, minimum: 0 }
+    probability: { type: number, minimum: 0, maximum: 1 }
+    open: { type: boolean }
+    closes_at: { type: string, format: date-time }
+    contact_email: { type: string, format: email }
+    note: { type: [string, 'null'] }
+    shipping: { $ref: '#/$defs/address' }
+    tags: { type: array, items: { type: string }, maxItems: 3 }
+    lines:
+      type: array
+      items:
+        type: object
+        properties:
+          product: { type: string }
+          quantity: { type: integer, minimum: 1 }
+        required: [product, quantity]
+    blocks:
+      type: array
+      items:
+        oneOf:
+          - properties:
+              kind: { const: paragraph }
+              text: { type: string }
+            required: [kind, text]
+          - properties:
+              kind: { const: quiz }
+              question: { type: string }
+            required: [kind, question]
+    attributes:
+      type: object
+      additionalProperties: { type: string }
+  required: [title, company, stage]
+  if:
+    properties:
+      stage: { const: won }
+    required: [stage]
+  then:
+    required: [amount]
+  sections:
+    Description: { kind: text }

package/fixtures/cases/binary-any-reference/expected.json

@@ -2,6 +2,5 @@
   "verdict": "refuse",
   "file": "notes/draft.md",
   "rule": "unresolved-reference",
-  "version": "<package-version>",
-  "location": "subject"
+  "location": "/subject"
 }

package/fixtures/cases/binary-any-reference/schema.yaml

@@ -0,0 +1,4 @@
+note:
+  properties:
+    subject: { type: string, reference: any }
+  required: [subject]

package/fixtures/cases/binary-document-collision/expected.json

@@ -1,6 +1,5 @@
 {
   "verdict": "refuse",
   "file": "notes/draft.md",
-  "rule": "binary-target-document",
-  "version": "<package-version>"
+  "rule": "binary-target-document"
 }

package/fixtures/cases/binary-document-collision/schema.yaml

@@ -0,0 +1 @@
+note: {}

package/fixtures/cases/binary-link-outside-collection/expected.json

@@ -1,6 +1,5 @@
 {
   "verdict": "refuse",
   "file": "notes/draft.md",
-  "rule": "unresolved-link",
-  "version": "<package-version>"
+  "rule": "unresolved-link"
 }

package/fixtures/cases/binary-link-outside-collection/schema.yaml

@@ -0,0 +1 @@
+note: {}

package/fixtures/cases/binary-prototype-reference/expected.json

@@ -2,6 +2,5 @@
   "verdict": "refuse",
   "file": "notes/draft.md",
   "rule": "unresolved-reference",
-  "version": "<package-version>",
-  "location": "subject"
+  "location": "/subject"
 }

package/fixtures/cases/binary-prototype-reference/schema.yaml

@@ -0,0 +1,4 @@
+note:
+  properties:
+    subject: { type: string, reference: any }
+  required: [subject]

package/fixtures/cases/binary-typed-reference/expected.json

@@ -2,6 +2,5 @@
   "verdict": "refuse",
   "file": "notes/draft.md",
   "rule": "unresolved-reference",
-  "version": "<package-version>",
-  "location": "subject"
+  "location": "/subject"
 }

package/fixtures/cases/binary-typed-reference/schema.yaml

@@ -0,0 +1,5 @@
+note:
+  properties:
+    subject: { type: string, reference: person }
+  required: [subject]
+person: {}

package/fixtures/cases/boolean-field/context.json

@@ -0,0 +1 @@
+{ "binaryTargets": [] }

package/fixtures/cases/boolean-field/expected.json

@@ -0,0 +1,6 @@
+{
+  "verdict": "refuse",
+  "file": "deals/renewal.md",
+  "location": "/open",
+  "rule": "type"
+}

package/fixtures/cases/boolean-field/library/companies/acme.md

@@ -0,0 +1,4 @@
+---
+type: company
+name: Acme
+---

package/fixtures/cases/boolean-field/library/deals/renewal.md

@@ -0,0 +1,31 @@
+---
+type: deal
+title: Renewal
+company: ../companies/acme.md
+stage: won
+amount: 1200
+probability: 0.5
+open: "no"
+closes_at: 2026-10-10T09:30:00Z
+contact_email: ana@example.com
+note: null
+shipping:
+  city: Paris
+  country: FR
+tags: [renewal, priority]
+lines:
+  - product: seats
+    quantity: 10
+  - product: support
+    quantity: 1
+blocks:
+  - kind: paragraph
+    text: Signed.
+  - { kind: quiz, question: Renew next year? }
+attributes:
+  region: emea
+---
+
+## Description
+
+The yearly renewal.

package/fixtures/cases/boolean-field/schema.yaml

@@ -0,0 +1,56 @@
+$defs:
+  address:
+    type: object
+    properties:
+      city: { type: string }
+      country: { type: string, pattern: '^[A-Z]{2}$' }
+    required: [city]
+company:
+  properties:
+    name: { type: string }
+deal:
+  type: object
+  properties:
+    title: { type: string, minLength: 1, maxLength: 40 }
+    company: { type: string, reference: company }
+    stage: { enum: [lead, proposal, won, lost], default: lead }
+    amount: { type: integer, minimum: 0 }
+    probability: { type: number, minimum: 0, maximum: 1 }
+    open: { type: boolean }
+    closes_at: { type: string, format: date-time }
+    contact_email: { type: string, format: email }
+    note: { type: [string, 'null'] }
+    shipping: { $ref: '#/$defs/address' }
+    tags: { type: array, items: { type: string }, maxItems: 3 }
+    lines:
+      type: array
+      items:
+        type: object
+        properties:
+          product: { type: string }
+          quantity: { type: integer, minimum: 1 }
+        required: [product, quantity]
+    blocks:
+      type: array
+      items:
+        oneOf:
+          - properties:
+              kind: { const: paragraph }
+              text: { type: string }
+            required: [kind, text]
+          - properties:
+              kind: { const: quiz }
+              question: { type: string }
+            required: [kind, question]
+    attributes:
+      type: object
+      additionalProperties: { type: string }
+  required: [title, company, stage]
+  if:
+    properties:
+      stage: { const: won }
+    required: [stage]
+  then:
+    required: [amount]
+  sections:
+    Description: { kind: text }

package/fixtures/cases/bracketed-link-definition/schema.yaml

@@ -0,0 +1,6 @@
+task:
+  properties:
+    title: { type: string }
+  required: [title]
+  sections:
+    Description: { kind: text, required: true }

package/fixtures/cases/closed-nested-object/context.json

@@ -0,0 +1 @@
+{ "binaryTargets": [] }

package/fixtures/cases/closed-nested-object/expected.json

@@ -0,0 +1,6 @@
+{
+  "verdict": "refuse",
+  "file": "deals/renewal.md",
+  "location": "/shipping/cty",
+  "rule": "undeclared-field"
+}

package/fixtures/cases/closed-nested-object/library/companies/acme.md

@@ -0,0 +1,4 @@
+---
+type: company
+name: Acme
+---

package/fixtures/cases/closed-nested-object/library/deals/renewal.md

@@ -0,0 +1,32 @@
+---
+type: deal
+title: Renewal
+company: ../companies/acme.md
+stage: won
+amount: 1200
+probability: 0.5
+open: false
+closes_at: 2026-10-10T09:30:00Z
+contact_email: ana@example.com
+note: null
+shipping:
+  city: Paris
+  country: FR
+  cty: Lyon
+tags: [renewal, priority]
+lines:
+  - product: seats
+    quantity: 10
+  - product: support
+    quantity: 1
+blocks:
+  - kind: paragraph
+    text: Signed.
+  - { kind: quiz, question: Renew next year? }
+attributes:
+  region: emea
+---
+
+## Description
+
+The yearly renewal.

package/fixtures/cases/closed-nested-object/schema.yaml

@@ -0,0 +1,56 @@
+$defs:
+  address:
+    type: object
+    properties:
+      city: { type: string }
+      country: { type: string, pattern: '^[A-Z]{2}$' }
+    required: [city]
+company:
+  properties:
+    name: { type: string }
+deal:
+  type: object
+  properties:
+    title: { type: string, minLength: 1, maxLength: 40 }
+    company: { type: string, reference: company }
+    stage: { enum: [lead, proposal, won, lost], default: lead }
+    amount: { type: integer, minimum: 0 }
+    probability: { type: number, minimum: 0, maximum: 1 }
+    open: { type: boolean }
+    closes_at: { type: string, format: date-time }
+    contact_email: { type: string, format: email }
+    note: { type: [string, 'null'] }
+    shipping: { $ref: '#/$defs/address' }
+    tags: { type: array, items: { type: string }, maxItems: 3 }
+    lines:
+      type: array
+      items:
+        type: object
+        properties:
+          product: { type: string }
+          quantity: { type: integer, minimum: 1 }
+        required: [product, quantity]
+    blocks:
+      type: array
+      items:
+        oneOf:
+          - properties:
+              kind: { const: paragraph }
+              text: { type: string }
+            required: [kind, text]
+          - properties:
+              kind: { const: quiz }
+              question: { type: string }
+            required: [kind, question]
+    attributes:
+      type: object
+      additionalProperties: { type: string }
+  required: [title, company, stage]
+  if:
+    properties:
+      stage: { const: won }
+    required: [stage]
+  then:
+    required: [amount]
+  sections:
+    Description: { kind: text }

package/fixtures/cases/composed-root-reference/context.json

@@ -0,0 +1 @@
+{ "binaryTargets": [] }

package/fixtures/cases/composed-root-reference/expected.json

@@ -0,0 +1,6 @@
+{
+  "verdict": "refuse",
+  "file": "people/ada.md",
+  "rule": "referenced-missing-file",
+  "referrers": ["a.md"]
+}

package/fixtures/cases/composed-root-reference/library/a.md

@@ -0,0 +1,5 @@
+---
+type: task
+title: A
+owner: people/ada.md
+---

package/fixtures/cases/composed-root-reference/schema.yaml

@@ -0,0 +1,13 @@
+$defs:
+  assigned:
+    properties:
+      owner: { type: string, reference: person }
+    required: [owner]
+person:
+  properties:
+    name: { type: string }
+task:
+  allOf:
+    - $ref: '#/$defs/assigned'
+  properties:
+    title: { type: string }

package/fixtures/cases/date-time-format/context.json

@@ -0,0 +1 @@
+{ "binaryTargets": [] }

package/fixtures/cases/date-time-format/expected.json

@@ -0,0 +1,6 @@
+{
+  "verdict": "refuse",
+  "file": "deals/renewal.md",
+  "location": "/closes_at",
+  "rule": "format"
+}

package/fixtures/cases/date-time-format/library/companies/acme.md

@@ -0,0 +1,4 @@
+---
+type: company
+name: Acme
+---

package/fixtures/cases/date-time-format/library/deals/renewal.md

@@ -0,0 +1,31 @@
+---
+type: deal
+title: Renewal
+company: ../companies/acme.md
+stage: won
+amount: 1200
+probability: 0.5
+open: false
+closes_at: 2026-10-10
+contact_email: ana@example.com
+note: null
+shipping:
+  city: Paris
+  country: FR
+tags: [renewal, priority]
+lines:
+  - product: seats
+    quantity: 10
+  - product: support
+    quantity: 1
+blocks:
+  - kind: paragraph
+    text: Signed.
+  - { kind: quiz, question: Renew next year? }
+attributes:
+  region: emea
+---
+
+## Description
+
+The yearly renewal.