@agentshouse/mdmodel 0.1.0-ccf1367190878 → 0.1.0-cdbd463e01dc2

package/API.md

@@ -26,15 +26,13 @@ if (checked.verdict === 'accept') {
 }
 const parsed = parse(content);
 if (parsed.ok) {
-  for (const link of links(parsed.document, 'tasks/two.md')) {
-    if (link.target !== 'data/export.csv') continue;
-    const moved = apply(parsed.document, {
-      kind: 'link',
-      href: link.href,
-      to: '../files/export.csv',
-    });
-    if (moved.outcome === 'applied') serialize(moved.document);
-  }
+  const moved = apply(
+    parsed.document,
+    links(parsed.document, 'tasks/two.md')
+      .filter((link) => link.target === 'data/export.csv')
+      .map((link) => ({ kind: 'link' as const, href: link.href, to: '../files/export.csv' })),
+  );
+  if (moved.outcome === 'applied') serialize(moved.document);
 }
 ```
 
@@ -45,13 +43,19 @@ if (parsed.ok) {
 (draft 2020-12) in the YAML subset. Every top-level key but `$defs` names an MD Type holding the
 JSON Schema of its frontmatter; `$defs` holds shapes the types reuse, reached by a `$ref` under
 `#/$defs/` alone. `type` and the built-in `any` are never declared. The model adds its keywords:
-`reference` on a string names one MD Type, several, `any` or `attachment`; `sections` declares a
+`reference` on a string names one MD Type, several, `any` or `attachment`, and `cross_room: true`
+beside it admits a Document in another Room, of a type that Room declares; `sections` declares a
 type's H2 sections, each `{ kind: text }` or `{ kind: list, items }` over one string, number,
-integer or boolean, optionally `required: true`; `member_document: true` marks at most one type. A
-type alone takes `create_roles` and `delete_roles`, each a list of role names. On a field of a
-type's own `properties` alone, `change_roles` and `initial_roles` each list role names, and
+integer or boolean, optionally `required: true`, which the `then` or `else` of an `if` on the type,
+in its `allOf` or in such a branch may repeat to ask a section for text, else `conditional-section`;
+`member_document: true` marks at most one type. A type alone takes `create_roles` and
+`delete_roles`, each a list of role names. `verify(schema, provided)` holds every type of a model
+`provided` as its own, named only for those two and only if `provided.nameable` lists it. On a field
+of a type's own `properties` alone, `change_roles` and `initial_roles` each list role names, and
 `transitions` lists `{ from, to, roles? }`, each end a scalar or `null`, on a field whose `type`,
 `enum`, `const`, `$ref`, `allOf`, `anyOf`, `oneOf`, `if` and `not` admit no list or object.
+`readTypes(schema, provided?)` returns the model of a schema `verify` already accepted, checking
+none of these rules, and throws on a text it cannot read as types.
 
 ```yaml
 $defs:
@@ -76,48 +80,55 @@ to their siblings and the variants of `anyOf`, `oneOf`, `then`, `else` and `depe
 variant's own keys `conditional`; a path without one `type`, `null` aside, has none. A malformed
 schema is refused whole, naming its `rule`, the keyword or the model's own, and the JSON Pointer
 `location` it concerns, such as `/plan/properties/status/enum`, or `line <n>` outside the YAML
-subset. `pointerFacts(definition, pointer)` reads the facts a frontmatter pointer reaches,
-`itemFacts` and `memberFacts` take one step and `crossedFacts` reads a list's item facts;
-`pointerSegments` and `escapePointer` split and write a pointer, `ARRAY_INDEX` matches an index
-segment, and `ATTACHMENT` is the `reference` that admits any path.
-
-`validate(library, context?, model?)` takes the resulting text Library and one `ValidationContext`
-of `binaryTargets: readonly string[]`, none when omitted. Library keys and binary targets share one
-canonical collection-relative path namespace; a path declared text and binary is refused. House
-declares every binary file of the Room as a binary target, and the model reads no bytes. Ordinary
-links and images in typed Documents may resolve to either membership, relative to the source
-Document, and one to a path neither holds is not refused: it dangles, as a deleted file's links do.
-A destination that is an absolute path or leaves the collection is `unresolved-link`. A binary
-target supplies no Document or MD Type. `model` is the verified schema that types the Library, and
-every Library member is content, whatever its Path. Without `model` the Library declares no type.
+subset. `pointerFacts(definition, pointer)` reads the facts a frontmatter pointer reaches, `itemFacts`
+and `memberFacts` take one step and `crossedFacts` reads a list's item facts; `JSON_POINTER` matches the
+JSON Pointer grammar, `''` included, `pointerSegments` and `escapePointer` split and write a pointer,
+`ARRAY_INDEX` matches an index segment, and `ATTACHMENT` is the `reference` that admits any path.
+
+`validate(library, context?, model?)` takes the resulting text Library and one `ValidationContext` of
+`binaryTargets: readonly string[]`, none when omitted. Library keys and binary targets share one
+canonical collection-relative path namespace; a path declared text and binary is refused. House declares
+every binary file of the Room as a binary target, and the model reads no bytes. Ordinary links and
+images in typed Documents may resolve to either membership, relative to the source Document, and one to
+a path neither holds is not refused: it dangles. One written `/rooms/<handle>/<path>` names a file in
+another Room, which the caller checks; any other absolute path, or one that leaves the collection, is
+`unresolved-link`. A binary target supplies no Document or MD Type. `model` types the Library. A typed
+Document, `any` included, at an `isDocumentPath` (no `isReservedName` of `RESERVED_NAMES` first) linking
+into a reserved name is `unresolved-link`; a typed `ROOM_DESCRIPTION` is `room-md-type`. The context's `typedPaths` bind each `path`, a name's one `*` standing for any nonempty part, to a `type` of `model`: a Document there naming another, or naming any unless `named`, is `unknown-type` at `/type`, one not `named` is checked as it and stays `any`, and one whose body is empty is `required-body` if `body`.
 
 A typed Document's frontmatter satisfies its type's schema, every keyword with its JSON Schema
 meaning, formats asserted and defaults never filled, except that an object schema declaring neither
 `additionalProperties` nor `unevaluatedProperties` is closed: an undeclared key is refused as
-`undeclared- field`. `TYPE_FIELD`, `SITE_FIELD` and `RECEIVED_FIELD` count as declared on every
-type, and the string `MEMBER_FIELD` on the `member_document` type; `HOUSE_FIELDS` lists the four. A
-refusal names the keyword, such as `required`, and the value's JSON Pointer, such as
-`/shipping/city`. Every occurrence of a declared list section is a list of values of its item
-schema, else `structured-section`; a reference item is one ordinary link alone, such as
-`- [Ada](ada.md)`. A reference, at any depth or a section item, reaching a URL, a binary target, or a
-Document of a type it does not name is `unresolved-reference`, and a frontmatter one reaching no
-member is `referenced-missing-file` naming its `referrers`; `attachment` admits any path, and no
-body link is a referrer.
+`undeclared-field`. `TYPE_FIELD`, `SITE_FIELD` and `RECEIVED_FIELD` count as declared on every type,
+and the string `MEMBER_FIELD` on the `member_document` type alone, else refused, `any` included;
+`HOUSE_FIELDS` lists the four. A refusal names the keyword, such as `required`, and the value's JSON
+Pointer, such as `/shipping/city`. Every occurrence of a declared list section is a list of values of
+its item schema, else `structured-section`; a reference item is one ordinary link alone, such as
+`- [Ada](ada.md)`. A reference, at any depth or a section item, reaching a URL, a binary target, another
+Room without `cross_room` or the context's `anyRoom: true`, a Document of a type it does not name, or,
+from an `isDocumentPath`, a reserved name is `unresolved-reference`, and a frontmatter one reaching no member is `referenced-missing-file`
+naming its `referrers`; `attachment` admits any path, and no body link is a referrer. `validating` is
+`validate` over a `ReadonlyMap` Library, yielding each path read with the references it `resolved`;
+`assess(file, content, binary, model?, context?)` reads one member, naming its `type` and `targets`,
+and `verdicts()` `add`s assessments in any order, its `verdict()` the one `validate` gives.
 
 Validation returns acceptance or one refusal naming the file, the field or section, and the violated
 rule. `parse`, `apply`, and `serialize` operate on a single text Document; they do not validate
-collection membership or consume binary bytes. `apply` sets one typed field, including a list or an
-object as a whole, replaces one existing section body or the preamble against that value's prior
-content, or rewrites one Markdown link destination. A section need not be declared by the Document's
-MD Type to be replaced. A section or preamble replacement that would hide a section the Document
-carried behind a repeated, merged or fenced heading is refused as `overlapping-section` naming that
-section. A field change does not reformat the rest of the file: an inline value is replaced where it
-stands, and a value written after the key's line, an empty one or a block mapping or list, is
-written after the key's colon in its place. A field holds a `FrontmatterValue`: null, a string, a
-boolean, a finite number, a list without holes or a plain object of them, holding no cycle.
-`frontmatterValue(value)` is that test, and `apply` refuses any other value as `frontmatter-fence`;
-`equalValue(left, right)` compares two by value, whatever their key order, as `apply` compares a
-field with its prior.
+collection membership or consume binary bytes. `apply(document, changes)` applies a list of changes
+in one pass however many: each sets one typed field, a list or an object as a whole included,
+replaces one existing section body or the preamble against its prior content, or rewrites one link
+destination or one reference, as the given Document holds it. All apply or none: one refused refuses
+all, and `{ outcome: 'stale', document, stale }` keeps the Document and lists the positions of each
+change it does not hold and of each later change of a part an earlier one changes, such as a link
+inside a replaced section. A section need not be declared by the Document's MD Type to be replaced.
+A section or preamble replacement that would hide a section the Document carried behind a repeated,
+merged or fenced heading is refused as `overlapping-section` naming that section. A field change
+does not reformat the rest of the file: an inline value is replaced where it stands, and a value
+written after the key's line, an empty one or a block mapping or list, is written after the key's
+colon in its place. A field holds a `FrontmatterValue`: null, a string, a boolean, a finite number,
+a list without holes or a plain object of them, no cycle, at most 63 deep. `frontmatterValue(value)`
+is that test; `apply` refuses any other value and `parse` a frontmatter past 64 deep as
+`frontmatter-fence`. `equalValue` compares two by value, whatever their key order, as `apply` does.
 
 `Document.preamble` is a readonly string holding the exact source after frontmatter and before the
 first section heading the section parser recognizes, `''` when empty, whitespace, newlines, a
@@ -134,24 +145,22 @@ if (parsed.ok) {
     prior: parsed.document.preamble,
     value: 'Updated introduction.\n\n',
   };
-  const result = apply(parsed.document, change);
+  const result = apply(parsed.document, [change]);
   if (result.outcome === 'applied') serialize(result.document);
 }
 ```
 
-`apply(document, { kind: 'preamble', prior, value })` compares `prior` to the current preamble
-exactly. A mismatch returns `{ outcome: 'stale', document }` with the unchanged current Document. A
-match replaces only that source span, then parses a new immutable Document; the original is
-unchanged. Frontmatter and section source outside the span retain their exact bytes, including
-newline and heading syntax. As with section replacement, `value` is literal source: no newline or
-separator is inserted, and the resulting source is parsed again. An invalid frontmatter result
-receives the existing parse refusal. Independent field, section, and preamble edits keep their own
-prior values valid.
+A `{ kind: 'preamble', prior, value }` change compares `prior` to the current preamble exactly. A
+mismatch is stale and leaves the current Document unchanged. A match replaces only that source span,
+then parses a new immutable Document; the original is unchanged. Frontmatter and section source
+outside the span retain their exact bytes, including newline and heading syntax. As with section
+replacement, `value` is literal source: no newline or separator is inserted, and the resulting
+source is parsed again. An invalid frontmatter result receives the existing parse refusal.
+Independent field, section, and preamble edits keep their own prior values valid.
 
-For a moved link, use `links` and the `link` change below to obtain the rewritten Document, then
-compare its public `preamble` and `sections` to the original. Submit the changed values with their
-original priors. Consumers need no source span calculation or private Model import. Collection
-validation remains a separate call against the resulting Library.
+For moved links, use `links` and one `link` change per destination below, then compare the rewritten
+Document's `preamble` and `sections` to the original and submit the changed values with their
+original priors. Collection validation remains a separate call against the resulting Library.
 
 `links(document, file)` is the inventory of that Document's ordinary link and image destinations
 that resolve to a collection Path, each with the destination `href` exactly as written and the
@@ -160,8 +169,7 @@ is part of `href` and not part of `target`. Entries are ordered by the position
 text a rewrite would change, and one destination written the same way appears once however many
 times it occurs. A destination that the syntax profile does not read as a link, one that is empty, a
 bare fragment, or carries a URL scheme, and one that leaves the collection are not in the inventory.
-Frontmatter values are never link destinations. `linkOccurrences(document, file)` places each
-occurrence by its `start` in `content`, and `fieldStart(document, pointer)` a frontmatter value.
+Frontmatter values are never link destinations.
 
 `target(file, href)` is the collection Path one written destination resolves to relative to `file`,
 by the rule `links` and `validate` read: surrounding spaces and the `?query` or `#fragment` it
@@ -170,36 +178,43 @@ URL does, then percent-encodings, so `plan\.md`, `pl&#97;n.md` and `pl%61n.md` a
 an escaped or referenced `?` or `#` starts the suffix. A destination that is empty, a bare fragment,
 carries a URL scheme, starts at `/` once read, encodes no UTF-8 text, or leaves the collection
 resolves to `null`. It reads a destination written anywhere, such as a typed reference field value,
-which `links` never enumerates. `retarget(href, to)` is that destination rewritten to `to`, keeping
-the `?query` or `#fragment` it carried, which is the destination the `link` change below writes. It
+which `links` never enumerates. `roomTarget(href)` reads `/rooms/<handle>/<path>` as its `handle`
+and `path`, else `null`, and `roomPath(href)` is its canonical text, the target `facts` resolves for
+any reference written so. `retarget(href, to)` is that destination rewritten to `to`, keeping the
+`?query` or `#fragment` it carried, which is the destination the `link` change below writes. It
 percent-encodes in `to` what `target` would decode, so it resolves to `to` again.
 
-`checkDocument(file, content, model)` reads one Document alone by the same rules: `ok: false` where
-`validate` refuses it, else its `type`, whether it is `typed`, and each reference's `target` and
-`to`, which `resolves(reference, typeOf, binary)` says reaches a member `validate` accepts.
-`sectionReferences(file, content, definition)` reads only the references of its `list` sections.
-`parseFrontmatter(content, file?)` is `parse` without the body: `content`, `type` and `fields`.
+`checkDocument(file, content, model, context?)` reads one Document as `validate` does in that
+context: `ok: false` where it refuses, else its `type`, whether it is `typed`, and each reference's
+`target` and `to`, which `resolves(reference, typeOf, binary)` says reaches a member `validate`
+accepts. It names no other Room's, which `roomReferences(file, content, definition?)` lists by `kind`.
+`parseFrontmatter(content, file?)` is `parse` without the body: `content`, `type`, `fields`.
 
 `references(document, definition)` lists each frontmatter `reference` string at any depth as
-`pointer`, `value` and `to`; `apply(document, { kind: 'reference', pointer, value, prior })`
-rewrites one in place, keeping its quotes, or is `stale`. `relativize(document, file, handle,
-definition?)` rewrites each link destination and reference written `/rooms/<handle>/<path>` to
-`relative(file, path)`, keeping its `?query` or `#fragment`. A text without frontmatter, such as
-a captured body, is read from its first character: `relativizeBody(body, file, handle)` converts
-it so, refusing a destination left under `/rooms/` as `unresolved-link`; `bodyLinks(body, file)`
-is its `links`; `relinkBody(body, file, moves)` writes, in one pass, each destination whose Path
-is a key of `moves` as relative to its value, in the form the `link` change below writes.
+`pointer`, `value` and `to`; a `{ kind: 'reference', pointer, value, prior }` change rewrites one in
+place, keeping its quotes, or is stale. `referenceTarget(file, value)` is the Path a value names
+read as a link destination, else `null`; `referenceTargets(document, file, model)` lists each
+reference's `location`, `to` and `target`. `documentFacts(file, content, model)`, `null` where the
+text does not parse, is the `type` (`any` if none), `fields` and sorted distinct link and reference
+`links` a save stores, no links under `settings/`. `relativize(document, file, handle, definition?, kept?)`
+rewrites, in one `apply`, each link destination and reference written `/rooms/<handle>/<path>` and
+not in `kept` to `relative(file, path)`, keeping its `?query` or `#fragment`. A text without
+frontmatter, such as a captured body, is read from its first character: `relativizeBody(body, file, handle)` converts it
+so, refusing a `/rooms/` one naming no Room's file as `unresolved-link`; `bodyLinks(body, file)`
+is its `links` and `bodyRoomLinks(body)` its other Rooms'. `relinkBody(body, file, moves)` writes,
+in the `link` change's form, each destination whose Path keys `moves` as that value relative to
+`file`, or as that value when it is a `/rooms/` path, and one whose `roomPath` does as that value.
 
 ```ts
 target('items/six.md', ' ../projects/atlas.md#overview '); // 'projects/atlas.md'
 retarget(' ../projects/atlas.md#overview ', '../archive/atlas.md'); // '../archive/atlas.md#overview'
 ```
 
-`apply(document, { kind: 'link', href, to })` rewrites every body occurrence of that written
-destination and changes nothing else, so a caller that moves a Path rewrites its referring
-Documents without a second Markdown parser. `to` is the Path the destination must resolve to
+A `{ kind: 'link', href, to }` change rewrites every body occurrence of that written destination
+and changes nothing else, so a caller that moves Paths rewrites each referring Document in one
+`apply` without a second Markdown parser. `to` is the Path the destination must resolve to
 instead; the `?query` or `#fragment` the written destination carried is not part of that Path and
-is kept. A Document that does not carry the destination is `stale`. A reference definition is
+is kept. A Document that does not carry the destination is stale. A reference definition is
 rewritten once however many uses name it. The destination is written in the form the syntax
 profile reads back: bare when it carries no whitespace, does not open with `<`, and balances its
 parentheses, otherwise inside angle brackets, which the original form is kept in when it still
@@ -231,29 +246,25 @@ if (parsed.ok) {
 Markdown documents, and `definition`, the verified MD Type the Document's `type` names, taken from
 the model `verify` returned. A Document that declares a type the caller supplies no definition for
 is refused as `unknown-type`. `documentTargets` is what makes a destination internal: a destination
-resolving to a supplied Path is internal, and every other destination stays authored text, a binary
-target and a Path nobody supplied alike. The caller supplies that membership, as it does for
-`validate`; the model reads no bytes, resolves no authority, and classifies nothing it was not
-given.
-
-An internal link contributes its visible label and no destination, fragment, or
-title, in the inline `[label](path)`, full `[label][id]`, collapsed
-`[label][]`, and shortcut `[label]` forms, and the link reference definition an
-enumerated use resolves through leaves the projection with it. An image at a
-supplied document target contributes its alt text the same way, because a move
-rewrites that destination too. External URLs, binary targets,
-unsupplied destinations, bare fragments, code spans, fenced code, and escaped
-syntax stay exactly as authored, read through the same syntax profile `links`
-and `validate` read. `project` returns text and never rewrites the Document.
+resolving to a supplied Path is internal, as is one into another Room, and every other stays text, a
+binary target and a Path nobody supplied alike. The caller supplies that membership, as it does for
+`validate`; the model reads no bytes, resolves no authority, and classifies nothing unsupplied.
+
+An internal link contributes its visible label and no destination, fragment, or title, in the inline
+`[label](path)`, full `[label][id]`, collapsed `[label][]`, and shortcut `[label]` forms, and the
+link reference definition an enumerated use resolves through leaves the projection with it. An image
+at a supplied document target contributes its alt text the same way, because a move rewrites that
+destination too. External URLs, binary targets, unsupplied destinations, bare fragments, code spans,
+fenced code, and escaped syntax stay exactly as authored, read through the same syntax profile
+`links` and `validate` read. `project` returns text and never rewrites the Document.
 
 A `link` change leaves the projection of every Document it rewrites
 byte-identical, while a changed visible label changes it.
 
 `divide(document, file, context)` divides that same Embedding projection input into ordered Spans
-under the budget the caller supplies. Each Span carries the `text` to embed and the `start` and
-`end` of the extent it addresses in the Document's own source, as UTF-8 byte offsets into that
-source and never string positions, so a caller stores the extent and hydrates the text it shows from
-the Document itself.
+under the bound the caller supplies. Each Span carries the `text` to embed and the `start` and `end`
+of the extent it addresses in the Document's own source, as UTF-8 byte offsets and never string
+positions, so a caller stores the extent and hydrates the text it shows from the Document itself.
 
 ```ts
 const parsed = parse(content);
@@ -261,25 +272,22 @@ if (parsed.ok) {
   const divided = divide(parsed.document, 'tasks/two.md', {
     documentTargets: ['plans/q3.md', 'people/ana.md'],
     definition: model.types.task,
-    budget: 2000,
+    bound: 2000,
   });
   if (divided.ok) for (const span of divided.spans) embed(span.text);
 }
 ```
 
-`DivisionContext` is a `ProjectionContext` and one `budget`, the greatest number
-of characters a Span's embedded text may carry, counted the way JavaScript
-counts a string's length and not in the bytes the extent is measured in. No
-Span's text is ever longer than the budget. A bound cut never divides a
-character: where the budget ends between the two halves of a surrogate pair,
-the cut falls before the pair. A cut never falls inside link syntax either: it
-falls before an internal link, and a label longer than a whole piece's room is
-divided at the bound like any other text. The smallest budget is `2`, the
-length of one astral character; a budget that is not a whole number of at least
-`2` is refused with `division-budget` before any division. The budget is the
-caller's number alone: the model holds no tokenizer, counts nothing else, and
-refuses no input for being too long. A Document the caller supplies no
-definition for carries the same `unknown-type` refusal `project` returns.
+`DivisionContext` is a `ProjectionContext` and one `bound`, the greatest number of characters a
+Span's embedded text may carry, counted the way JavaScript counts a string's length and not in the
+bytes the extent is measured in. No Span's text is ever longer than the bound. A bound cut never
+divides a character: where the bound ends between the two halves of a surrogate pair, the cut falls
+before the pair. A cut never falls inside link syntax either: it falls before an internal link, and
+a label longer than a whole piece's room is divided at the bound like any other text. The smallest
+bound is `2`, the length of one astral character; a bound that is not a whole number of at least
+`2` is refused with `division-bound` before any division. The bound is the caller's number alone:
+the model holds no tokenizer, counts nothing else, and refuses no input for being too long. A
+Document the caller supplies no definition for carries the `unknown-type` refusal of `project`.
 
 The division descends one level at a time, and only into the piece that does not fit: the whole
 input, a heading node, adjacent sibling nodes packed under one parent, adjacent blocks inside a
@@ -287,73 +295,84 @@ node, sentences inside a block, and a bound cut inside a single sentence. A Span
 heading nodes or one contiguous piece inside a single node, never a partial node beside another. A
 Span that continues a node repeats that node's own heading line, projected like any other text and
 so carrying an internal link's label rather than its destination, and never an ancestor's heading,
-so renaming a heading costs what editing that heading's own body costs. A heading the budget cannot
+so renaming a heading costs what editing that heading's own body costs. A heading the bound cannot
 hold beside any text is not repeated, a continuation piece that begins with an astral character the
 room beside its heading cannot hold is carried without the heading, and a heading with no body of
 its own leads its first child node rather than standing as a Span of nothing but itself. Overlap
 exists at the sentence level alone, where each Span after the first repeats its predecessor's last
-sentence whenever the budget holds both; when it cannot hold both, the Span carries its own sentence
+sentence whenever the bound holds both; when it cannot hold both, the Span carries its own sentence
 alone. An untyped input arrives without a definition and descends the same ladder.
 
-Division is total: every authored character of the input belongs to at least one
-Span, and an input carrying no authored text divides into no Span at all. A
-Span's extent is the smallest range of the source that contains everything the
-Span covers, so it spans what the input excludes between two eligible pieces,
-and the extent addresses the authored source where the embedded text carries a
-repeated heading, an internal link's visible label, or a frontmatter value the
-author quoted. A Span divided out of one free-text field value addresses that
-whole value, because a YAML scalar's own positions are the only ones its source
-has, and a Span carrying part of one internal link's label addresses that whole
-link, because a cut never falls inside link syntax.
-
-## Conditions
-
-`facts(document, { id, path }, model, resolve)` reads one Document as the `DocumentFacts` a
-condition tests: its `id`, its `path` with a leading `/`, its `type` or `null`, its `sections`, and
-a `Fact` for each frontmatter field it writes that its MD Type declares. `factKind(facts)` names
-the kind a declared value compares as: `reference`, `enum`, `number`, `boolean`, `date`, `time`
-(a `date-time`) or `string`, else `null`. A prose value, or one of no kind, is `prose`, a list or
-an object holds the facts of its members, and a value written `null` is `null`. A value that does
-not fit its kind, such as a string in a number field, a value outside its `enum` or a reference
-`resolve` maps to no `{ id, member? }`, is `unreadable`; a readable reference compares as that `id`.
-
-`holds(test, facts, owner)` is `true`, `false` or `undefined`, unknown; a Trigger fires on `true`
-alone. A test's `path` is `/path`, `/type`, `/sections/<heading>`, `/fields/<pointer>`, or
-`/members/<pointer>`, the member of the Document a reference field reaches. A pointer segment that
-is not an index reads every item of a list, an item lacking it unknown, and a test over several
-values holds as `any` does. The value `{ owner: true }` stands for `owner`, a User id.
-
-| The path reaches                        | `exists`    | `contains`     | any other test |
-| --------------------------------------- | ----------- | -------------- | -------------- |
-| a value                                 | present     | `undefined`    | compared       |
-| `null`, prose or a section              | present     | `undefined`    | `undefined`    |
-| a list                                  | present     | `any` of items | `undefined`    |
-| no item, through an empty list          | absent      | `false`        | `false`        |
-| nothing: no such field, section or type | absent      | `undefined`    | `undefined`    |
-| only unreadable values                  | `undefined` | `undefined`    | `undefined`    |
-
-`exists: true` holds where present and fails where absent, `exists: false` the reverse. `all` is
-`false` if a part is, else `undefined` if a part is; `any` is `true` if a part is, else `undefined`
-if a part is; `not` keeps `undefined`, so absence is tested with `exists`, never with `not`. `eq`
-and `in` are `undefined` against a value of another JSON type and compare a `time` as an instant;
-`prefix` reads only a string, never a reference or a member; `gt`, `gte`, `lt` and `lte` order
-numbers, dates and times alone.
-
-`fires(condition, event, owner)` reads one change, `{ before, after, changed, by }`: the facts of
-each side, `null` on the side a creation or a deletion lacks, the `changed` paths whose prose
-changed, and the actor whose `/user`, `/site` and `/door`, one of `WRITE_DOORS`, a `by` test reads.
-`starts_matching` fires when the Document is in `scope` and holds `match` after the change and did
-not before; a creation fires only with `new_documents: true`, and a deletion never fires.
-`field_changes` fires when the side the Document has, after or for a deletion before, is in `scope`
-and holds `match`, and `field` changed: its facts differ, or with neither `from` nor `to` `changed`
-names it. A field absent on both sides never fires; `from: 'new'` admits only a creation and
-`to: 'deleted'` only a deletion, and listed values need that side to hold `field` `in` them.
-
-`itemFires(condition, item, owner)` compares `source` and `address` where given and holds `match`
-over `/delivery`, `/source`, `/container`, `/author`, `/has_attachment`,
-`/headers/<name>` and `/json/<pointer>`, unknown for an item with no JSON. `prosePaths(facts)` lists
-the prose and section paths whose text builds `changed`; `pointed(value, pointer)` reads a JSON
-Pointer, `undefined` where nothing is; `dated(value)` checks a `YYYY-MM-DD` date, and
-`instant(value)` reads an RFC 3339 time with its offset as epoch nanoseconds, a `bigint`.
-`datePointers(fields)` lists, sorted, the `/fields/<name>` pointers of a type's date fields, the
-only values a `DateCondition`'s `date` takes.
+Division is total: every authored character of the input belongs to at least one Span, and an input
+carrying no authored text divides into no Span at all. A Span's extent is the smallest range of the
+source that contains everything the Span covers, so it spans what the input excludes between two
+eligible pieces, and the extent addresses the authored source where the embedded text carries a
+repeated heading, an internal link's visible label, or a frontmatter value the author quoted. A Span
+divided out of one free-text field value addresses that whole value, because a YAML scalar's own
+positions are the only ones its source has, and a Span carrying part of one internal link's label
+addresses that whole link, because a cut never falls inside link syntax.
+
+## Queries
+
+`planOf(query, rooms)` checks one query against the MD Types of the Rooms `rooms` lists, each
+`{ locator, available, types }` with `listed` when the list is whole, and answers its
+`QueryPlan` or throws a `QueryError` whose `code` is `invalid-query`, `unknown-type`,
+`unknown-field` or `wrong-kind`, whose message names where, whose `place` is that place as the
+keys and indexes into the query, which `placeText` writes as its message does, and whose `accepts` lists what it would take there: the types or
+fields the Rooms declare, a field's `kindWords`, or the parts and operators a query knows. A query
+is data: `types`, `where`
+field predicates by JSON Pointer (`$eq`, `$ne`, `$in`, `$nin`, `$gt`, `$gte`, `$lt`, `$lte`,
+`$all`, `$size`, `$exists`, `$prefix`, `$and`, `$or`), `pathPrefix`, `folder`, `paths`,
+`fileIds`, `hop`, `backlinks`, `text`, then `select` or `groupBy`, `orderBy`, `limit`, `after`
+and `total`. `queryKey` and `identityOf` are a query's and a plan's canonical text, `bodied`
+says a shape reads text, `cursorOf` and `decodedCursor` write and read the `after` a window
+continues from, and `invalid`, `known` and `plain` are the check's refusal and tests.
+
+`KINDS` is the one table of kinds a value compares as, `kindOf(facts)` a declared value's kind,
+`kindWords(facts)` the values it takes in words, and `fitsKind(kind, facts, value)` whether a value
+fits it: a `date`, `date-time` or `time` is
+exactly what document validation admits as that format, a `date` is `dated`, a `date-time`
+compares as the instant `instant` reads, which `instantKey` writes as text that sorts as the
+instant does, and a `reference` as the Room Path it resolves to. `compared(left, right,
+ordering)` orders plain values: numbers and booleans, then text by locale or `byCodePoint`,
+then lists item by item.
+
+Two evaluators answer a plan's tests on one Document alike, a test on a missing value false and
+its negation (`$ne`, `$nin`, `$exists: false`) true. `matches(plan, candidate)` answers in
+memory over one `Candidate`: its `path`, `type`, `fileId`, `fields`, `definition` and the
+`text` held. The `sql` namespace compiles them to SQL over a collection: `indexed(path, fields,
+definition)` derives a Document's values and field links, its date-times with their instants,
+`sql.VALUE_TABLE` holds those values and `sql.insertedValues` writes them, and `sql.tests(alias,
+plan)` tests a document row of `id`, `path`, `folder`, `type`, `file_id` and `content`, its
+phrase through the function a connection registers as `sql.HOLDS_PHRASE` with `sql.holdsPhrase`.
+`sql.scoped`, `sql.placed`, `sql.sorted`, `sql.beyond`, `sql.following` and `sql.sortValue`
+render a scope, a pointer, an order and a window's continuation, a date-time ordering as its
+instant between numbers and text; `sql.fragment`, `sql.joined`, `sql.all`, `sql.any`,
+`sql.grouped`, `sql.listed` and `sql.exists` build statements, and `heldKind` is the index's value
+kind. `fixtures/queries.json` holds both evaluators to one table.
+
+## Events
+
+`facts(document, { id, path }, model, resolve)` reads one Document as the `DocumentFacts` of a
+change: its `id`, its `path` with a leading `/`, its `type` or `null`, its `sections`, and a `Fact`
+for each frontmatter field it writes that its MD Type declares, held as its kind: `reference`,
+`enum`, `number`, `boolean`, `date`, `time` (a `date-time`) or `string`. A prose value, or one of
+no kind, is `prose`, a list or an object holds the facts of its members, and a value written
+`null` is `null`. A
+value that does not fit its kind, such as a string in a number field, a value outside its `enum` or
+a reference `resolve` maps to no `{ id, member? }`, is `unreadable`; a readable reference holds that
+`id` and the `member` it binds, which `members(facts, path)` lists at a `/members/<pointer>`.
+
+`candidateOf(facts)` is that Document as the `Candidate` `matches` answers over, so a query tests
+the Document as the change saw it: at its Room Path, by its file ID, a reference as the `id` it
+named, a prose value as present alone, an unreadable value as missing and a date-time as an instant.
+`heldAt(candidate, pointer)` lists the values a pointer reaches there, its date-times with their
+instants. `prosePaths(facts)` lists the prose and section paths whose text a change compares, and
+`TEXT_FIELD`, `/text`, names a Document's whole text; `WRITE_DOORS` are the ways a change is made.
+`pointed(value, pointer)` reads a JSON Pointer, `undefined` where nothing is; `dated(value)` checks a
+`YYYY-MM-DD` date, and `instant(value)` reads what validation admits as a `date-time` as epoch
+nanoseconds, a `bigint`. Of one MD Type, `datePointers(definition)` lists, sorted, its date fields as
+escaped pointers, `valuedChange(definition, pointer)` holds of a field read as one value, never
+prose, a list or reached through one, the only field whose change is tested by its values, and
+`memberPointers(definition, memberType)` the `/members/<name>` paths of the fields referring to
+`memberType`, alone or in a list.

package/README.md

@@ -1,11 +1,12 @@
 # `@agentshouse/mdmodel`
 
-Typed Markdown documents: MD Types declared in JSON Schema, a parser, a validator, and the
-deterministic application of one structured change to a Document, plus a
-conformance fixture corpus.
+Typed Markdown documents: MD Types declared in JSON Schema, a parser, a validator, the
+deterministic application of one structured change to a Document, and one query language
+answered in SQL over a collection or in memory over one Document, plus a conformance
+fixture corpus.
 
 It runs in the browser and in Node, makes no network call, and reads no
-filesystem on its own. It ships one ESM artifact that Node 24.21.0 and later
+filesystem on its own. It ships one ESM artifact that Node 24.22.1 and later
 loads through `import` or `require`.
 
 ## Install
@@ -26,30 +27,28 @@ if (checked.verdict === 'accept') {
 
 const parsed = parse('---\ntype: note\ntitle: Hello\n---\n');
 if (parsed.ok) {
-  const next = apply(parsed.document, {
-    kind: 'field',
-    name: 'title',
-    value: 'World',
-    prior: 'Hello',
-  });
+  const next = apply(parsed.document, [
+    { kind: 'field', name: 'title', value: 'World', prior: 'Hello' },
+  ]);
   if (next.outcome === 'applied') serialize(next.document);
 }
 ```
 
 ## API
 
-| Export                                         | Purpose                                                           |
-| ---------------------------------------------- | ----------------------------------------------------------------- |
-| `verify`                                       | Verify one schema text into a model of MD Types                   |
-| `validate`                                     | Validate a text Library; returns acceptance or one refusal        |
-| `parse`, `serialize`                           | Read and write one Document                                       |
-| `apply`                                        | Apply one field, section, preamble, or link change                |
-| `links`, `target`, `retarget`                  | Inventory and rewrite link destinations                           |
-| `escapePointer`                                | Write one key as a JSON Pointer token                             |
-| `project`, `divide`                            | Embedding projection input and its division into Spans            |
-| `facts`, `factKind`, `holds`, `fires`          | A condition over a Document and over one of its changes           |
-| `MARKDOWN_SYNTAX_PROFILE`, `VERSION`           | The pinned Markdown profile (GFM 0.29) and MD model version       |
-| `MEMBER_FIELD`, `SITE_FIELD`, `RECEIVED_FIELD` | The field names validation counts as declared beyond a type's own |
+| Export                                         | Purpose                                                            |
+| ---------------------------------------------- | ------------------------------------------------------------------ |
+| `verify`                                       | Verify one schema text into a model of MD Types                    |
+| `validate`                                     | Validate a text Library; returns acceptance or one refusal         |
+| `parse`, `serialize`                           | Read and write one Document                                        |
+| `apply`                                        | Apply field, section, preamble, link and reference changes at once |
+| `links`, `target`, `retarget`                  | Inventory and rewrite link destinations                            |
+| `escapePointer`                                | Write one key as a JSON Pointer token                              |
+| `project`, `divide`                            | Embedding projection input and its division into Spans             |
+| `facts`, `candidateOf`                         | A Document as one change saw it, matched as one query candidate    |
+| `planOf`, `matches`, `sql`                     | Check a query, answer it over one Document or compile it to SQL    |
+| `MARKDOWN_SYNTAX_PROFILE`, `VERSION`           | The pinned Markdown profile (GFM 0.29) and MD model version        |
+| `MEMBER_FIELD`, `SITE_FIELD`, `RECEIVED_FIELD` | The field names validation counts as declared beyond a type's own  |
 
 The full reference is in [`API.md`](API.md). The conformance corpus and its
 verdict format and rule ids are described in [`fixtures/README.md`](fixtures/README.md).

package/dist/blocks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"blocks.d.ts","sourceRoot":"","sources":["../src/blocks.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,CAAC;AAqCF,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,WAAW,EAAE,CA+BrF;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,CAe/E"}
+{"version":3,"file":"blocks.d.ts","sourceRoot":"","sources":["../src/blocks.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,CAAC;AAoDF,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,WAAW,EAAE,CA4BrF;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,CAe/E"}