From 10570b75f87a99a236d3da53a6954155c61645a7 Mon Sep 17 00:00:00 2001 From: claude Date: Sat, 25 Jul 2026 04:33:25 +0200 Subject: [PATCH] =?UTF-8?q?docs(guide,=20ledger,=20glossary):=20the=20elev?= =?UTF-8?q?enth=20op=20=E2=80=94=20naming=20a=20blueprint=20from=20the=20s?= =?UTF-8?q?cript?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The authoring guide's ops table grows the name row (ten -> eleven) plus a paragraph on what the graph default costs a multi-strategy project (indistinguishable store entries, one shared trace directory, colliding use-splice instance defaults). C24's op-script grammar records the eleventh verb and the two-seam shape gate with its C29 read-back exemption; the glossary's blueprint-label entry now separates the render name (op-settable, keys trace runs and instance defaults) from the registry label (register --name, explicit, orthogonal). refs #331 --- docs/authoring-guide.md | 11 ++++++++++- docs/design/contracts/c24-blueprint-data.md | 9 ++++++++- docs/glossary.md | 2 +- 3 files changed, 19 insertions(+), 3 deletions(-) diff --git a/docs/authoring-guide.md b/docs/authoring-guide.md index a700233..e3827dd 100644 --- a/docs/authoring-guide.md +++ b/docs/authoring-guide.md @@ -227,10 +227,11 @@ $ aura graph build < smacross.json > blueprint.json Nodes are referenced by an **identifier** (given by `add`, see below); ports are dotted `.` on both sides of a wire. -### The ten ops +### The eleven ops | op | JSON shape | does | |---|---|---| +| `name` | `{"op":"name","name":}` | set the composite's **render name**, script-level and at-most-once (a second `name` op refuses: `a script names its blueprint at most once`). The name must be a single path segment (non-empty, no `/`, `\`, `.` or `..`) since it keys a trace directory (`traces//`) at run time. Omitting the op keeps the CLI's own default, `"graph"`. | | `doc` | `{"op":"doc","text":}` | declare the composite's one-line meaning (C29) — the op-script twin of the Rust builder's `.doc(...)`. Required before `aura graph register` accepts the product (the store refuses a doc-less composite); at most one per script (a second refuses: `a doc op may appear at most once`). The text is gated: empty or merely restating the composite's name refuses at register. | | `source` | `{"op":"source","role":,"kind":}` | reserve a bound root **source** role of `kind` — a real input the harness feeds (e.g. `"price"`). | | `input` | `{"op":"input","role":}` | reserve an open root **input** role (kind inferred from the slots it feeds) — the formal parameter of an **open pattern**, a fragment meant to be wired by an *enclosing* graph. An open pattern builds and registers like any blueprint. Running it standalone is governed by the ordinary run gates: the harness binds input roles to archive columns **by name** (C26), so a pattern whose roles match the data runs as-is; what refuses, by name, is a role the harness cannot bind — or the run surface's other gates (a signal without a bias output or tap; free knobs). | @@ -242,6 +243,14 @@ are dotted `.` on both sides of a wire. | `tap` | `{"op":"tap","from":,"as":}` | declare a **measurement tap** on an interior output field under the name `as` — the output-side twin of `expose` (a recorded observation point, not a boundary output; a `Composite.taps` entry, C27). A single `aura run` constructs a recorder at each declared tap and persists its per-cycle series as a `ColumnarTrace`; a sweep leaves it inert. Tap names are their own namespace and must be unique (a second `tap` under one name refuses: `duplicate tap name`). | | `gang` | `{"op":"gang","as":"channel_length","into":["channel_hi.length","channel_lo.length"]}` | Fuse two or more sibling params into ONE public knob: the member addresses leave the sweepable param space and `as` replaces them; the bound or swept value fans out to every member at bootstrap. Members must share one scalar kind and stay open (un-bound). | +Omitting `name` is fine for a single strategy, but it has three live +consequences once a project has more than one: every unnamed store document +is indistinguishable by name (`"graph"` again), every unnamed strategy's +default tap recording lands in the same shared `traces/graph/` directory +(later runs overwrite earlier ones), and two `use`-splices of unnamed +blueprints collide on the same default instance identifier (`graph`) inside +the same composing script. A one-line `name` op dissolves all three at once. + Value forms are the typed-tag representations used everywhere in this family of artifacts: diff --git a/docs/design/contracts/c24-blueprint-data.md b/docs/design/contracts/c24-blueprint-data.md index 41d24fe..7ea6f49 100644 --- a/docs/design/contracts/c24-blueprint-data.md +++ b/docs/design/contracts/c24-blueprint-data.md @@ -196,8 +196,15 @@ rejected at construction. The op-script is a JSON **array of ops**, each object internally tagged by `"op"`, replayed in order; nodes are referenced **by identifier**, ports as dotted -`.`. The ten verbs: +`.`. The eleven verbs: +- `name` — `{"op":"name","name":}` — set the composite's render name + (#331), script-level and at-most-once (a second refuses); omitted, the + built composite keeps the CLI's own seed default (`"graph"`). Gated by a + shared shape check (non-empty, single path segment, no `/`, `\`, `.` or + `..`) applied at both data-borne birth routes — this op intake and the + blueprint-envelope root name — since store read-back (reproduce, `use` + resolution) stays ungated per C29. - `source` — `{"op":"source","role":,"kind":}` — declare a root source role producing a base column of `kind`. - `input` — `{"op":"input","role":}` — declare a root input role (kind inferred diff --git a/docs/glossary.md b/docs/glossary.md index 768593a..a7b805e 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -37,7 +37,7 @@ The param-generic, input-role-generic graph-as-data produced by running a Rust b ### blueprint label **Avoid:** — -A registry-level name pointing at a registered blueprint's content id (`graph register --name