@osqd/jql 0.1.1

package/docs/course/03-arrays-and-paths.md

@@ -0,0 +1,239 @@
+# Lesson 3 — Arrays and paths
+
+**Goal:** know exactly what happens when a path meets an array. This is the lesson that stops
+you writing a filter that looks right and is not.
+
+← [Course](index.md) · Previous: [Asking precisely](02-operators.md) · Next: [Combining and negating](04-combining.md)
+
+---
+
+## The rule
+
+A path like `customer.country` is resolved one segment at a time. On an object, take the
+field. On an array, one of two things happens:
+
+- the segment is a **number** — take that position, so `lines.0.sku` is the first line's sku;
+- the segment is anything else — apply it to **every element**. The array is *seen through*.
+
+Because of the second case a path can reach **several values at once**, and then:
+
+> **A condition holds when it holds for any one of the values the path reached.**
+
+That one sentence explains almost every surprise in this language. The rest of this lesson is
+four small programs showing what it does.
+
+## A value matches any element
+
+```js
+import { filter } from "@osqd/jql";
+import { orders } from "./orders.mjs";
+
+const repeat = filter(orders, { tags: "repeat" });
+
+console.log(repeat.map((order) => `${order.id} ${JSON.stringify(order.tags)}`));
+```
+
+```
+[
+  'o-1003 ["repeat"]',
+  'o-1004 ["damaged","repeat"]',
+  'o-1008 ["repeat"]'
+]
+```
+
+`tags` is a list, and `"repeat"` is not a list — so the condition is tried against each tag in
+turn, and one match is enough. You do not write anything special to search inside a list.
+
+## A path can go through one
+
+```js
+import { filter } from "@osqd/jql";
+import { orders } from "./orders.mjs";
+
+const ids = (query) => filter(orders, query).map((order) => order.id);
+
+console.log("any line is a fine liner  ", ids({ "lines.sku": "pen-fine" }));
+console.log("the FIRST line is one     ", ids({ "lines.0.sku": "pen-fine" }));
+```
+
+```
+any line is a fine liner   [ 'o-1001', 'o-1003', 'o-1006' ]
+the FIRST line is one      [ 'o-1001', 'o-1003' ]
+```
+
+`lines.sku` reaches the sku of *every* line. `lines.0.sku` reaches exactly one value, because
+`0` is a position rather than a field name. `o-1006` has a fine liner as its second line, so
+it answers the first question and not the second.
+
+## The trap
+
+Here is the mistake this lesson exists for. Read this query aloud:
+
+```json
+{ "lines.quantity": { "$gt": 5 }, "lines.price": { "$gt": 100 } }
+```
+
+Most people say *"a line of more than five, at over a hundred pounds"*. Now run it:
+
+```js
+import { filter } from "@osqd/jql";
+import { orders } from "./orders.mjs";
+
+const found = filter(orders, { "lines.quantity": { $gt: 5 }, "lines.price": { $gt: 100 } });
+
+for (const order of found) {
+  console.log(order.id);
+  for (const line of order.lines) console.log("   ", line.quantity, "x", line.title, "@", line.price);
+}
+```
+
+```
+o-1005
+    1 x Desk lamp @ 140
+    10 x A5 pad @ 3
+```
+
+There is no expensive bulk line in that order at all. The query says **"some line has
+quantity over five, *and* some line costs over a hundred"** — and `o-1005` satisfies it with
+two *different* lines.
+
+Each condition is resolved on its own, and each is happy as soon as any one element satisfies
+it. Nothing ties them to the same element unless you say so.
+
+## `$elemMatch` says "the same element"
+
+```js
+import { filter } from "@osqd/jql";
+import { orders } from "./orders.mjs";
+
+const ids = (query) => filter(orders, query).map((order) => order.id);
+
+console.log("big AND expensive, same line:", ids({
+  lines: { $elemMatch: { quantity: { $gt: 5 }, price: { $gt: 100 } } },
+}));
+
+console.log("at least 2, at least £9     :", ids({
+  lines: { $elemMatch: { quantity: { $gte: 2 }, price: { $gte: 9 } } },
+}));
+```
+
+```
+big AND expensive, same line: []
+at least 2, at least £9     : [ 'o-1004', 'o-1007' ]
+```
+
+The first is empty, which is the true answer: nobody has bought more than five of anything
+costing over a hundred pounds. The second shows `$elemMatch` finding real matches, so you can
+see it is not simply stricter about everything.
+
+Both readings are legitimate — "this order has a big line *and* an expensive line" is a real
+question someone might ask. The danger is that the loose one is what you get by default, and
+in small test data the two usually agree.
+
+**Rule of thumb:** the moment a query puts two conditions on the *same array*, stop and decide
+whether they must hold of the same element. If they must, it is `$elemMatch`.
+
+## `$all` — several values, any elements
+
+```js
+import { filter } from "@osqd/jql";
+import { orders } from "./orders.mjs";
+
+const ids = (query) => filter(orders, query).map((order) => order.id);
+
+console.log("repeat            ", ids({ tags: "repeat" }));
+console.log("repeat AND damaged", ids({ tags: { $all: ["repeat", "damaged"] } }));
+```
+
+```
+repeat             [ 'o-1003', 'o-1004', 'o-1008' ]
+repeat AND damaged [ 'o-1004' ]
+```
+
+`$all` is the other half of the pair: *every one of these values is somewhere in the list*,
+each possibly in a different element. Use `$all` for a set of tags, `$elemMatch` for several
+facts about one object.
+
+## Counting: `$size` and `$length`
+
+```js
+import { filter } from "@osqd/jql";
+import { orders } from "./orders.mjs";
+
+const ids = (query) => filter(orders, query).map((order) => order.id);
+
+console.log("exactly two lines", ids({ lines: { $size: 2 } }));
+console.log("no tags at all   ", ids({ tags: { $size: 0 } }));
+console.log("exactly two tags ", ids({ tags: { $length: 2 } }));
+```
+
+```
+exactly two lines [ 'o-1001', 'o-1004', 'o-1005', 'o-1006', 'o-1008' ]
+no tags at all    [ 'o-1002', 'o-1006' ]
+exactly two tags  [ 'o-1004' ]
+```
+
+`$size` counts elements. `$length` measures an array **or a string** — its elements, or its
+UTF-16 code units — and accepts a nested condition, so `{ $length: { $gt: 18 } }` is a valid
+question about a note.
+
+Unlike the string operators, neither of these is tried against the elements. If `$length` were
+seen through the array, `{ tags: { $length: 1 } }` would mean both "one tag" and "a tag one
+character long" at once, with nothing in the query to say which.
+
+## The same rule, all the way down
+
+The "seen through" rule applies at *every* segment, including before the first one — an item
+that is itself an array is seen through too:
+
+```js
+import { filter } from "@osqd/jql";
+
+const nested = [[{ sku: "pen-fine" }], [{ sku: "ink-red" }]];
+
+console.log("item is a list of objects:", filter(nested, { sku: "pen-fine" }).length);
+console.log("items are bare numbers   :", filter([3, 8, 1, 12], { $gt: 5 }));
+```
+
+```
+item is a list of objects: 1
+items are bare numbers   : [ 8, 12 ]
+```
+
+The second line is worth a moment. `{ $gt: 5 }` has no field name in it at all — a field
+operator at the top of a query is a condition on **the item itself**. That is how you query a
+list of numbers, or of strings, where there is no field to name.
+
+## Exercise
+
+Find the orders containing a line of **ten or more A5 pads**. Then try the same question
+without `$elemMatch`, and work out why it is not a safe way to write it.
+
+<details>
+<summary>Answer</summary>
+
+```js
+import { filter } from "@osqd/jql";
+import { orders } from "./orders.mjs";
+
+const ids = (query) => filter(orders, query).map((order) => order.id);
+
+console.log("with $elemMatch   :", ids({ lines: { $elemMatch: { sku: "pad-a5", quantity: { $gte: 10 } } } }));
+console.log("without $elemMatch:", ids({ "lines.sku": "pad-a5", "lines.quantity": { $gte: 10 } }));
+```
+
+```
+with $elemMatch   : [ 'o-1002', 'o-1005' ]
+without $elemMatch: [ 'o-1002', 'o-1005' ]
+```
+
+The two agree — on *this* data, because in both orders it really is the pad line that is
+large. That is exactly why the loose version survives testing: it needs a row where the two
+conditions land on different elements before it goes wrong, and your fixtures probably do not
+have one.
+</details>
+
+## Related
+
+- [Specification §3](../reference/specification.md#3-paths) — path resolution, formally
+- [Specification §4.1](../reference/specification.md#41-how-a-condition-meets-an-array) — the "any of them" rule

package/docs/course/04-combining.md

@@ -0,0 +1,221 @@
+# Lesson 4 — Combining and negating
+
+**Goal:** `$or`, `$nor` and `$not` — and what negation means when a path reaches more than one
+value.
+
+← [Course](index.md) · Previous: [Arrays and paths](03-arrays-and-paths.md) · Next: [Dates and windows](05-dates.md)
+
+---
+
+## Four operators that take whole queries
+
+Two keys side by side already mean *and*. For everything else there are four operators whose
+arguments are themselves queries:
+
+| | |
+| --- | --- |
+| `$and: [ … ]` | every one of them holds |
+| `$or: [ … ]` | at least one holds |
+| `$nor: [ … ]` | none of them holds |
+| `$not: { … }` | this one does not hold |
+
+They nest freely, and `$not` may sit at the very top of a query, which makes "everything
+except this saved filter" a one-character change.
+
+The first half of this lesson is mechanical. The second half — negation over a list, and
+negation of a field nobody filled in — is where the surprises are.
+
+## `$or` and `$and`
+
+```js
+import { filter } from "@osqd/jql";
+import { orders } from "./orders.mjs";
+
+const ids = (query) => filter(orders, query).map((order) => order.id);
+
+console.log("cancelled OR over £150:", ids({
+  $or: [{ status: "cancelled" }, { total: { $gt: 150 } }],
+}));
+
+console.log("paid AND under £20    :", ids({
+  $and: [{ status: "paid" }, { total: { $lt: 20 } }],
+}));
+```
+
+```
+cancelled OR over £150: [ 'o-1005', 'o-1007' ]
+paid AND under £20    : [ 'o-1003', 'o-1008' ]
+```
+
+That `$and` could have been written `{ status: "paid", total: { $lt: 20 } }`. You need the
+spelled-out form only when two branches would collide on the same key — two different
+conditions on `total`, say, or a list of filters you built in a loop and cannot merge into one
+object.
+
+## `$nor` and `$not`
+
+```js
+import { filter } from "@osqd/jql";
+import { orders } from "./orders.mjs";
+
+const ids = (query) => filter(orders, query).map((order) => order.id);
+
+console.log("neither paid nor open :", ids({ $nor: [{ status: "paid" }, { status: "open" }] }));
+console.log("not a British customer:", ids({ $not: { "customer.country": "GB" } }));
+console.log("$not on a field       :", ids({ status: { $not: { $in: ["paid", "open"] } } }));
+```
+
+```
+neither paid nor open : [ 'o-1004', 'o-1007' ]
+not a British customer: [ 'o-1002', 'o-1004', 'o-1006', 'o-1007', 'o-1008' ]
+$not on a field       : [ 'o-1004', 'o-1007' ]
+```
+
+`$nor` is "none of these". `$not` comes in two positions: wrapped around a **whole query**, as
+on the second line, and inside a **field's condition**, as on the third.
+
+The first and third lines returned the same two orders, and that is not a coincidence — they
+are the same question written two ways. Reach for whichever reads better where it is written:
+`$nor` when the alternatives are whole queries, `$not` on the field when they are all about
+one field.
+
+## Negation is about *all* the values, not one of them
+
+Now the lesson. `o-1004` is tagged `["damaged", "repeat"]`. Watch where it appears:
+
+```js
+import { filter } from "@osqd/jql";
+import { orders } from "./orders.mjs";
+
+const ids = (query) => filter(orders, query).map((order) => order.id);
+
+console.log("has the tag repeat    :", ids({ tags: "repeat" }));
+console.log("$ne repeat            :", ids({ tags: { $ne: "repeat" } }));
+console.log("an element that is not:", ids({ tags: { $elemMatch: { $ne: "repeat" } } }));
+```
+
+```
+has the tag repeat    : [ 'o-1003', 'o-1004', 'o-1008' ]
+$ne repeat            : [ 'o-1001', 'o-1002', 'o-1005', 'o-1006', 'o-1007' ]
+an element that is not: [ 'o-1001', 'o-1004', 'o-1005', 'o-1007' ]
+```
+
+`o-1004` is in the **first and third** lists at once. That is not a contradiction:
+
+- `$ne` holds when **no** value the path reached equals `"repeat"`. `o-1004` has one that
+  does, so it fails.
+- `$elemMatch` holds when **some** element satisfies the condition inside. `o-1004` has the
+  tag `"damaged"`, which is not `"repeat"`, so it passes.
+
+Both are true of the same order. "Not tagged repeat" and "has a tag other than repeat" are
+different questions, and a list is exactly where they come apart.
+
+Every negating operator works this way. `$ne`, `$nin`, `$exists: false` and `$not` all hold
+when their positive counterpart holds for **none** of the reached values.
+
+## Negation and a field that is not there
+
+The same rule has a second consequence, and it catches people more often than the array one:
+
+```js
+import { filter } from "@osqd/jql";
+import { orders } from "./orders.mjs";
+
+const ids = (query) => filter(orders, query).map((order) => order.id);
+
+console.log("note is not 'x'      :", ids({ note: { $ne: "x" } }).length, "of 8");
+console.log("has a note, not 'x'  :", ids({ note: { $exists: true, $ne: "x" } }).length, "of 8");
+```
+
+```
+note is not 'x'      : 8 of 8
+has a note, not 'x'  : 5 of 8
+```
+
+A path that reaches nothing has no value equal to `"x"` — so `$ne` is satisfied, and the three
+orders with no `note` at all come back. This is consistent, but it is rarely what someone
+means by "everything except x".
+
+If you mean "has a note, and it is not x", say both things:
+
+```json
+{ "note": { "$exists": true, "$ne": "x" } }
+```
+
+## Empty lists
+
+```js
+import { count } from "@osqd/jql";
+import { orders } from "./orders.mjs";
+
+console.log("$and: [] matches", count(orders, { $and: [] }), "of 8");
+console.log("$or:  [] matches", count(orders, { $or: [] }), "of 8");
+```
+
+```
+$and: [] matches 8 of 8
+$or:  [] matches 0 of 8
+```
+
+An empty `$and` matches everything and an empty `$or` matches nothing. That looks asymmetric
+until you build the list in a loop: "no filters were selected" should narrow nothing, and "no
+alternatives were offered" should accept nothing. Refusing the empty list instead would turn a
+perfectly ordinary state of the user interface into an error every caller has to special-case.
+
+## `$comment`
+
+```js
+import { filter } from "@osqd/jql";
+import { orders } from "./orders.mjs";
+
+const found = filter(orders, { status: "paid", $comment: "the weekly reconciliation" });
+
+console.log(found.map((order) => order.id));
+```
+
+```
+[ 'o-1001', 'o-1003', 'o-1006', 'o-1008' ]
+```
+
+`$comment` decides nothing. It is there because a stored filter gets read by a person months
+later, and a sentence of intent beside it is worth more than a commit message they will not
+find. It is also dropped from the canonical form (lesson 13), so it never makes one filter
+look like two.
+
+## Exercise
+
+The support console wants a "needs attention" filter: orders with **no tags at all**, or **no
+note**. One query.
+
+<details>
+<summary>Answer</summary>
+
+```js
+import { filter } from "@osqd/jql";
+import { orders } from "./orders.mjs";
+
+const ids = (query) => filter(orders, query).map((order) => order.id);
+
+console.log("with $size:", ids({ $or: [{ tags: { $size: 0 } }, { note: { $exists: false } }] }));
+console.log("with []   :", ids({ $or: [{ tags: [] }, { note: { $exists: false } }] }));
+```
+
+```
+with $size: [ 'o-1002', 'o-1005', 'o-1006', 'o-1008' ]
+with []   : [ 'o-1002', 'o-1005', 'o-1006', 'o-1008' ]
+```
+
+The two agree, and it is worth knowing why they are not the same question.
+
+Equality is tried against **the whole array first**, and then against each element. So
+`{ tags: [] }` asks "is this array exactly the empty array?", while `{ tags: { $size: 0 } }`
+asks "how many elements are in it?". At zero they coincide. One step further and they part
+company: `{ tags: ["gift"] }` matches an order whose tags are exactly `["gift"]`, whereas
+`{ tags: { $size: 1 } }` matches an order with one tag whatever it is — so an order tagged
+`["fragile"]` satisfies the second and not the first.
+</details>
+
+## Related
+
+- [Specification §6.1](../reference/specification.md#61-combining-queries) — the combinators
+- [Specification §5.8](../reference/specification.md#58-not-on-a-field) — `$not` on a field

package/docs/course/05-dates.md

@@ -0,0 +1,214 @@
+# Lesson 5 — Dates and windows
+
+**Goal:** write an instant in JSON, and a window that still means the same thing next week.
+
+← [Course](index.md) · Previous: [Combining and negating](04-combining.md) · Next: [Typed queries](06-typed-queries.md)
+
+---
+
+## JSON has no date type
+
+So JQL adds one wrapper:
+
+```json
+{ "placed": { "$gte": { "$date": "2026-09-14" } } }
+```
+
+`{ "$date": … }` is the query **saying** that this comparison is about time. Without it a
+timestamp is a string, and is compared as one. The wrapper accepts four things:
+
+| | |
+| --- | --- |
+| `{ "$date": "2026-09-14" }` | an ISO 8601 date or timestamp |
+| `{ "$date": 1788254100000 }` | epoch milliseconds |
+| `{ "$date": "now" }` | the moment the query is compiled |
+| `{ "$date": { "$ago": "7d" } }` | that long before now — `$ahead` for the future |
+
+## A fixed window
+
+```js
+import { filter } from "@osqd/jql";
+import { orders } from "./orders.mjs";
+
+const ids = (query) => filter(orders, query).map((order) => order.id);
+
+console.log("on or after the 14th:", ids({ placed: { $gte: { $date: "2026-09-14" } } }));
+
+console.log("the 7th to the 18th :", ids({
+  placed: { $gte: { $date: "2026-09-07" }, $lt: { $date: "2026-09-18" } },
+}));
+```
+
+```
+on or after the 14th: [ 'o-1005', 'o-1006', 'o-1007', 'o-1008' ]
+the 7th to the 18th : [ 'o-1003', 'o-1004', 'o-1005' ]
+```
+
+Two operators in one condition, exactly as in lesson 2 — a window is just a range that happens
+to be made of instants.
+
+## A window that moves with the clock
+
+This is what `{ "$ago": … }` is for. A saved filter written this way means *"the last seven
+days"*, not *"since the Tuesday somebody saved it"*:
+
+```js
+import { filter } from "@osqd/jql";
+import { orders } from "./orders.mjs";
+
+// The clock is an argument, which is what makes this example reproducible.
+const now = () => Date.parse("2026-09-25T12:00:00Z");
+const ids = (query) => filter(orders, query, { now }).map((order) => order.id);
+
+console.log("the last seven days:", ids({ placed: { $gte: { $date: { $ago: "7d" } } } }));
+console.log("the last 36 hours  :", ids({ placed: { $gte: { $date: { $ago: "36h" } } } }));
+console.log("anything before now:", ids({ placed: { $lt: { $date: "now" } } }).length, "of 8");
+```
+
+```
+the last seven days: [ 'o-1006', 'o-1007', 'o-1008' ]
+the last 36 hours  : [ 'o-1008' ]
+anything before now: 8 of 8
+```
+
+## "Now" is an argument, not a clock
+
+Notice `{ now }` in that example. The current time is an **option you pass**, never something
+read from the environment behind your back. Two things fall out of that:
+
+- a relative window is testable without waiting for time to pass, which is the only reason the
+  output above can be printed in a document at all;
+- a scheduled job can ask for "the last hour" as of the hour it was *scheduled* for, rather
+  than the moment it happened to start.
+
+### The window is fixed when the query compiles
+
+```js
+import { compile } from "@osqd/jql";
+import { orders } from "./orders.mjs";
+
+const now = () => Date.parse("2026-09-25T12:00:00Z");
+const lastWeek = compile({ placed: { $gte: { $date: { $ago: "7d" } } } }, { now });
+
+console.log("first pass :", orders.filter(lastWeek).map((order) => order.id));
+console.log("second pass:", orders.filter(lastWeek).map((order) => order.id));
+```
+
+```
+first pass : [ 'o-1006', 'o-1007', 'o-1008' ]
+second pass: [ 'o-1006', 'o-1007', 'o-1008' ]
+```
+
+A relative date resolves **once**, when the query is compiled — not once per row. That matters
+more than it sounds. Resolving per comparison would judge two rows a second apart against two
+different windows, and a scan over a million rows takes long enough for that to happen. When
+you want the window to move, compile again; it costs well under a microsecond.
+
+## What counts as a date in a document
+
+The wrapper says how the *query* means its value. The other half of the contract is how the
+value in the **row** is read:
+
+```js
+import { filter } from "@osqd/jql";
+
+const held = [
+  { id: "iso-z", at: "2026-09-01T09:15:00Z" },
+  { id: "iso-no-offset", at: "2026-09-01T09:15:00" },
+  { id: "space", at: "2026-09-01 09:15:00" },
+  { id: "epoch", at: 1788254100000 },
+  { id: "date-object", at: new Date("2026-09-01T09:15:00Z") },
+  { id: "not-a-date", at: "1 September 2026" },
+];
+
+const seen = filter(held, { at: { $eq: { $date: "2026-09-01T09:15:00Z" } } });
+
+console.log(seen.map((row) => row.id));
+```
+
+```
+[ 'iso-z', 'iso-no-offset', 'space', 'epoch', 'date-object' ]
+```
+
+Five of the six are the same instant. A `Date` object, epoch milliseconds, or an ISO 8601
+string with either a `T` or a space all count. `"1 September 2026"` does not — even though
+JavaScript's own parser would accept it happily.
+
+That restriction is deliberate. Host date parsers accept things no standard requires
+(`"12/31/2020"` is a date in one country and nonsense in another), and a document that matched
+in one implementation and not in another would make the same query mean two things.
+
+### A timestamp with no offset is UTC
+
+`"2026-09-01T09:15:00"` means 09:15 **UTC**, not 09:15 wherever the process happens to be
+running — which is why `iso-no-offset` and `space` are in that list.
+
+JavaScript itself does not do this: it reads a date-only string as UTC and a timestamp without
+an offset as local time. A query language cannot afford that, or the same filter over the same
+data would give different answers in London and in Tokyo.
+
+### Nothing is a date unless the query says so
+
+```js
+import { filter } from "@osqd/jql";
+
+const held = [
+  { id: "iso-z", at: "2026-09-01T09:15:00Z" },
+  { id: "space", at: "2026-09-01 09:15:00" },
+  { id: "epoch", at: 1788254100000 },
+];
+
+console.log("with $date   :", filter(held, { at: { $eq: { $date: "2026-09-01T09:15:00Z" } } }).map((r) => r.id));
+console.log("without $date:", filter(held, { at: "2026-09-01T09:15:00Z" }).map((r) => r.id));
+```
+
+```
+with $date   : [ 'iso-z', 'space', 'epoch' ]
+without $date: [ 'iso-z' ]
+```
+
+Without the wrapper it is a string comparison, and only the row holding that exact string
+matches. No value is ever read as a date unless the query asked for it.
+
+## Durations
+
+`$ago` and `$ahead` take `ms`, `s`, `m`, `h`, `d` and `w`, in any order and as many as you
+like: `"90s"`, `"1h30m"`, `"7d"`, `"2w3d"`.
+
+Months and years are deliberately missing. Neither has a fixed length, and a window that
+changed size with the calendar is one nobody can reason about. Write `"30d"` and mean it.
+
+## Exercise
+
+Write the query behind a "paid this month" figure on the Harbour dashboard, for September
+2026. Fixed dates, not relative ones — a monthly total should not move.
+
+<details>
+<summary>Answer</summary>
+
+```js
+import { filter } from "@osqd/jql";
+import { orders } from "./orders.mjs";
+
+const paidInSeptember = filter(orders, {
+  status: "paid",
+  placed: { $gte: { $date: "2026-09-01" }, $lt: { $date: "2026-10-01" } },
+});
+
+console.log(paidInSeptember.map((order) => order.id));
+console.log("total:", paidInSeptember.reduce((sum, order) => sum + order.paid, 0));
+```
+
+```
+[ 'o-1001', 'o-1003', 'o-1006', 'o-1008' ]
+total: 72
+```
+
+Half-open — `$gte` the first of the month, `$lt` the first of the next — is the range to reach
+for by default. It has no gap and no overlap with the neighbouring month, whatever the
+precision of the timestamps involved.
+</details>
+
+## Related
+
+- [Specification §7](../reference/specification.md#7-dates) — the date rules in full