@agentshouse/mdmodel 0.1.0-c83456e1cebfb → 0.1.0-cad192ab63d5f

package/API.md

@@ -16,26 +16,16 @@ import {
   VERSION,
 } from '@agentshouse/mdmodel';
 
-validate({ 'note.md': '# Hello\n' });
-const checked = verify('types:\n  task:\n    fields:\n      title: { kind: string }\n');
+const checked = verify('task:\n  properties:\n    title: { type: string }\n');
 if (checked.verdict === 'accept') {
   validate(
     { 'tasks/one.md': '---\ntype: task\ntitle: Ship\n---\n![Figure](assets/figure.png)\n' },
     { binaryTargets: ['assets/figure.png'] },
     checked.model,
   );
-  const task = checked.model.types.task;
-  const titleKind = task?.fields.title?.kind;
 }
 const parsed = parse(content);
 if (parsed.ok) {
-  const next = apply(parsed.document, {
-    kind: 'field',
-    name: 'title',
-    value: 'World',
-    prior: 'Hello',
-  });
-  if (next.outcome === 'applied') serialize(next.document);
   for (const link of links(parsed.document, 'tasks/two.md')) {
     if (link.target !== 'data/export.csv') continue;
     const moved = apply(parsed.document, {
@@ -48,71 +38,88 @@ if (parsed.ok) {
 }
 ```
 
-`verify(schema)` reads one schema text, the MD Types of one Room or App, and
-returns a verified model whose `types` expose each MD Type's `name`,
-`memberDocument` flag, parsed field specs, and declared sections. The text is a
-YAML mapping in the frontmatter subset whose one key, `types`, maps each MD Type
-name to an entry of optional `fields`, `sections`, and boolean `member_document`:
+`MARKDOWN_SYNTAX_PROFILE` is the Markdown every reader here applies, GitHub Flavored Markdown
+0.29, and `VERSION` is the MD model version.
+
+`verify(schema)` reads one schema text, the MD Types of one Room or App: one JSON Schema document
+(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 three keywords:
+`reference` on a string names one MD Type, several, `any` or `attachment`; `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.
 
 ```yaml
-types:
-  plan:
-    fields:
-      title: { kind: string, required: true }
-      status: { kind: enum, values: [active, done] }
-      owner: { kind: reference, to: contact }
-    sections:
-      Goals: { kind: text }
-  contact:
-    member_document: true
-    fields:
-      name: { kind: string, required: true }
+$defs:
+  address: { type: object, properties: { city: { type: string } }, required: [city] }
+plan:
+  properties:
+    status: { enum: [active, done] }
+    owner: { type: string, reference: contact }
+    shipping: { $ref: '#/$defs/address' }
+  required: [status]
+  sections: { Goals: { kind: text, required: true } }
+contact: { member_document: true }
 ```
 
-A field spec names its `kind` and `required` flag; a list carries `of`, an enum
-carries `values`, and a reference carries `to`, which names `any` or a type of
-the same schema. At most one type is marked `member_document: true`. A
-malformed schema is refused whole, naming its `rule` and, where the
-rule concerns one part of the text, its `location`: a dotted path such as
-`types.plan.fields.status`, or `line <n>` where the text leaves the YAML subset.
-
-`validate(library, context?, model?)` takes the resulting text Library and one
-`ValidationContext` containing `binaryTargets: readonly string[]`. Omitting the
-context declares no binary targets. Library keys and binary targets use the
-same collection-relative path namespace; callers supply canonical paths, and
-a path declared as both text and binary is refused. Ordinary links and images
-in typed Documents may resolve to either membership, including relative
-normalization from the source Document. A binary target supplies no Document
-or MD Type and cannot satisfy a typed reference, including one to `any`.
-The existing `any` Document rules are unchanged.
-`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.
-
-A typed Document carries the frontmatter fields its MD type declares, plus
-`type`, `SITE_FIELD` and `RECEIVED_FIELD`, the `site` and `received` a Site
-submission adds; a Document of the type marked `member_document` also carries
-`MEMBER_FIELD`, `member`, a string, unless that type declares it. Any other field is refused as `undeclared-field` at that field name. A field
-name YAML carries to a record prototype, `__proto__` among them, is an ordinary
-undeclared field and is refused as one. Every occurrence of a declared list section is a list
-whose every item is one value of its declared item kind, or it is refused as `structured-section`.
-A free-text or string item is any text; a number, date, or enum item is that value alone, such
-as `- 3`; a reference item is one ordinary link alone, such as `- [Ada](ada.md)`, refused as
-`unresolved-reference` where it reaches a binary target, a URL, or another MD type's Document.
-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 field 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 field change does not reformat the rest of the file.
-
-`Document.preamble` is a readonly string containing the exact source after
-frontmatter and before the first section heading recognized by the existing
-section parser. Without a section it is the entire post-frontmatter body;
-without frontmatter it starts at the beginning of the Document. An empty span
-is `''`. It includes whitespace, newlines, a leading H1, and any fenced text
-before the first section. The closing frontmatter delimiter and its line ending
-belong to frontmatter. Section recognition and the syntax profile are unchanged.
+The model's `types` expose each MD Type's `name`, `memberDocument`, `sections`, `shape` (the type as
+written with every `$defs` shape it reaches), the facts of its `frontmatter` and `fields`, its
+top-level ones: JSON `type`, `format`, `values`, `reference` targets, `items`, `properties`, an open
+map's `patterns` and `additional`, and `prose`, a string with no `enum`, `const`, `format`,
+`pattern` or `reference`. Facts join `$ref` and `allOf` to their siblings and the variants of
+`anyOf`, `oneOf`, `then`, `else` and `dependentSchemas`, a 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.
+
+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.
+
+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.
+
+`Document.preamble` is a readonly string containing the exact source after frontmatter and before
+the first section heading recognized by the existing section parser. Without a section it is the
+entire post-frontmatter body; without frontmatter it starts at the beginning of the Document. An
+empty span is `''`. It includes whitespace, newlines, a leading H1, and any fenced text before the
+first section. The closing frontmatter delimiter and its line ending belong to frontmatter.
+`headingLines(content, from, to)` reads each ATX heading outside a fence, by `level` and `name`.
 
 ```ts
 const parsed = parse(content);
@@ -127,77 +134,84 @@ if (parsed.ok) {
 }
 ```
 
-`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.
-
-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.
-
-`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 `target` Path it resolves to relative to
-`file`. A `?query` or `#fragment` the destination carries is part of `href` and
-not part of `target`. Entries are ordered by the position of the destination
-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 field values,
-including typed references, are not link destinations and are never enumerated.
-
-`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 carries are not part of that Path. A
-destination that is empty, a bare fragment, carries a URL scheme, starts at `/`,
-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.
+`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.
+
+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.
+
+`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
+`target` Path it resolves to relative to `file`. A `?query` or `#fragment` the destination carries
+is part of `href` and not part of `target`. Entries are ordered by the position of the destination
+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.
+
+`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
+carries are not part of that Path. It reads backslash escapes and character references, strips as a
+URL does, then percent-encodings, so `plan\.md`, `pl&#97;n.md` and `pl%61n.md` all name `plan.md`;
+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
+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`.
+
+`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.
 
 ```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 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
-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 fits. A
-destination that neither form can carry is refused as `unwritable-link`.
+`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
+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
+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
+fits. A destination that neither form can carry is refused as `unwritable-link`.
 
 `project(document, file, context?)` is the Embedding projection input of one
 Document: the prose a consumer embeds, with every internal Markdown-document
 link reduced to the label a reader sees. A Document that declares no MD type
-contributes its body after the frontmatter fence. A Document that declares one
-contributes its free-text field values, its preamble, and every H2 section its
-MD type does not declare as structure, each section with its own heading line
-and every occurrence of a repeated name, in the order the Document carries
-them. A declared free-text section, a declared list section whose items are
-free text, and a section the MD type does not declare at all are all inside
-that input; a declared list section of any other item kind is not, so
-eligibility follows the declared kind rather than the form the author wrote.
-Each free-text field value is projected bare, without its field name and
-followed by a blank line, in the order the MD Type declares its fields, and
-every item of a free-text list field is one such value, projected as the author
-wrote it: the link inventory reads the body, so link syntax inside a
-frontmatter value is text like any other. The Document's Path and its typed
-fields of every other kind stay outside that input.
+contributes its body after the frontmatter fence. A typed one contributes its
+prose values, its preamble, and every H2 section its MD type does not declare as
+structure, each with its own heading line and every occurrence of a repeated
+name, in Document order: a declared text section, a list section of prose items
+and an undeclared section are in; a list section of any other item schema is
+not. A prose value is a frontmatter string at any depth whose schema is prose,
+projected bare and followed by a blank line, in the order the Document writes
+them, exactly as written. The Path and every other value stay outside, so
+changing them alone leaves the projection unchanged.
 
 ```ts
 const parsed = parse(content);
@@ -216,7 +230,7 @@ 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 retained binary target and a Path nobody
+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.
@@ -226,14 +240,13 @@ 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, retained binary targets,
+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.
 
-Because a moved Path changes destinations alone, applying a `link` change leaves
-the projection of every Document it rewrites byte-identical, while a changed
-visible label changes it.
+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
@@ -268,23 +281,19 @@ 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.
 
-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 node, sentences inside a block, and a bound cut
-inside a single sentence. A Span covers whole 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 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 alone. An untyped input arrives without a
-definition and descends the same ladder.
+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
+node, sentences inside a block, and a bound cut inside a single sentence. A Span covers whole
+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
+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
+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
@@ -296,3 +305,55 @@ 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`, `/provider`, `/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.

package/README.md

@@ -1,6 +1,6 @@
 # `@agentshouse/mdmodel`
 
-Typed Markdown documents: the MD Type language, a parser, a validator, and the
+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.
 
@@ -19,7 +19,7 @@ npm install @agentshouse/mdmodel
 ```ts
 import { apply, parse, serialize, validate, verify } from '@agentshouse/mdmodel';
 
-const checked = verify('types:\n  task:\n    fields:\n      title: { kind: string }\n');
+const checked = verify('task:\n  properties:\n    title: { type: string }\n');
 if (checked.verdict === 'accept') {
   validate({ 'tasks/one.md': '---\ntype: task\ntitle: Ship\n---\n' }, undefined, checked.model);
 }
@@ -45,7 +45,9 @@ if (parsed.ok) {
 | `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 |
 

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;AAmCF,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,WAAW,EAAE,CAiBrF;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;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"}

package/dist/blocks.js

@@ -1,5 +1,5 @@
 import { fenceSpans } from './links.js';
-const HEADING = /^(#{1,6})(?!#)[ \t]+(.+?)[ \t]*#*[ \t]*$/;
+const HEADING = /^(#{1,6})(?!#)[ \t]+(.+?)(?:[ \t]+#+)?[ \t]*$/;
 function lineAt(content, from, to) {
     const nl = content.indexOf('\n', from);
     const end = nl === -1 || nl >= to ? to : nl;
@@ -23,24 +23,38 @@ function scan(content, from, to, visit) {
         i = next;
     }
 }
+const HASH = 0x23;
 export function headingLines(content, from, to) {
     const found = [];
-    scan(content, from, to, (line) => {
-        if (line.fenced)
-            return;
-        const match = HEADING.exec(line.text);
-        const hashes = match?.[1];
-        const name = match?.[2];
-        if (hashes === undefined || name === undefined)
-            return;
-        found.push({
-            level: hashes.length,
-            name: name.trim(),
-            start: line.start,
-            textEnd: line.start + line.text.length,
-            next: line.next,
-        });
-    });
+    let fences = null;
+    let i = from;
+    while (i < to) {
+        const nl = content.indexOf('\n', i);
+        const end = nl === -1 || nl >= to ? to : nl;
+        const next = end === to ? to : end + 1;
+        if (content.charCodeAt(i) === HASH) {
+            fences ??= fenceSpans(content.slice(from, to));
+            const at = i - from;
+            if (!fences.some(([start, stop]) => at >= start && at < stop)) {
+                const { text } = lineAt(content, i, to);
+                const match = HEADING.exec(text);
+                const hashes = match?.[1];
+                const name = match?.[2];
+                if (hashes !== undefined && name !== undefined) {
+                    found.push({
+                        level: hashes.length,
+                        name: name.trim(),
+                        start: i,
+                        textEnd: i + text.length,
+                        next,
+                    });
+                }
+            }
+        }
+        if (next === i)
+            break;
+        i = next;
+    }
     return found;
 }
 export function blockRanges(content, from, to) {