From eb2b0a132c9d07b2435981e6e9494a3527515304 Mon Sep 17 00:00:00 2001 From: claude Date: Fri, 24 Jul 2026 22:05:34 +0200 Subject: [PATCH] docs(guide, glossary): pin each ArgKind's lexical canonical form MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fieldtest spec-gap ratified: Count is a plain positive decimal with no sign and no leading zeros ('03' refuses) — and the per-kind asymmetry against TimeOfDay's required zero-pad is deliberate, pinned with its rationale: canonical is each domain's conventional notation, fixed-width for wall-clock times, minimal for numbers. refs #271 --- docs/authoring-guide.md | 8 ++++++-- docs/glossary.md | 2 +- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/authoring-guide.md b/docs/authoring-guide.md index d3f486d..94bb315 100644 --- a/docs/authoring-guide.md +++ b/docs/authoring-guide.md @@ -361,8 +361,12 @@ construction-args channel — `args` configures it BEFORE `bind`: `tz` is `chrono_tz`'s own exact, case-sensitive IANA name (`"berlin"` refuses; `"Europe/Berlin"` accepts); `open` is strict zero-padded local `HH:MM` -(`"9:30"` refuses; `"09:30"` accepts) — the accepted string IS the canonical -form, no normalization. Giving `Session` no `args` at all refuses the `add` +(`"9:30"` refuses; `"09:30"` accepts); a `Count` arg (`LinComb`/`CostSum`'s +arity) is a plain positive decimal — no sign, no leading zeros (`"03"` +refuses; `"3"` accepts). The accepted string IS the canonical form, no +normalization — and note the deliberate asymmetry: each kind's canonical +form is its domain's conventional notation, fixed-width for wall-clock +times, minimal for numbers. Giving `Session` no `args` at all refuses the `add` op (`node is missing required arg "tz"`) — an arg-bearing type never silently enters the graph half-configured. `aura graph introspect --node Session` lists both declared `arg` rows with their kind and hint text before diff --git a/docs/glossary.md b/docs/glossary.md index 9370278..3abe727 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -13,7 +13,7 @@ Entries are alphabetical. ### arg kind **Avoid:** ArgKind, construction-arg type -The closed vocabulary of construction-arg value shapes (`Tz`/`TimeOfDay`/`Count`, #271) — deliberately NOT a `scalar base type`: args are bootstrap metadata, never streamed, so the two closedness axes stay separate. Each kind's accepted strict form IS its canonical form (an exact IANA name, zero-padded `HH:MM`, a plain positive decimal count) — there is no normalization layer, so a near-miss string refuses rather than being rewritten. +The closed vocabulary of construction-arg value shapes (`Tz`/`TimeOfDay`/`Count`, #271) — deliberately NOT a `scalar base type`: args are bootstrap metadata, never streamed, so the two closedness axes stay separate. Each kind's accepted strict form IS its canonical form (an exact IANA name; zero-padded `HH:MM`; a plain positive decimal count, no sign or leading zeros) — there is no normalization layer, so a near-miss string refuses rather than being rewritten. The per-kind forms are deliberately asymmetric (`"03"` refuses as a count while `"09:30"` requires the pad): canonical is each domain's conventional notation — fixed-width for wall-clock times, minimal for numbers. ### atomic sim unit **Avoid:** atomic unit, sim unit