&ND Core v2 Consumer-Conventions Boundary

This companion note separates fixed &ND Core v2 parsing and canonicalization from meanings owned by applications, rendering profiles, workflow systems, and trust policies.

“Consumer-owned” does not mean optional grammar. Core always supplies the stable AST field and canonical spelling. Core does not supply the vocabulary, presentation, workflow effect, network behavior, or execution policy layered on that field.

1. Processing Order

A conforming consumer:

1. parses and validates under the declared or host-selected Core version;

2. retains the Core AST without reinterpreting its fields;

3. applies an explicitly selected consumer convention or product policy.

A convention registry MUST NOT make invalid Core syntax valid, turn valid syntax into a Core parse error, rewrite Core canonical text, or infer the grammar version.

2. Supported Convention Surfaces

Core itself owns local-anchor identifier validation, uniqueness, case-sensitive matching, and whole-document fragment resolution. Consumers own scrolling, focus, history, and navigation UI after resolution succeeds.

Inline advisory content may become a hover/focus callout, an always-visible annotation, or another accessible UI. Core does not require the labels “hint” or “warning”; those remain projection policy.

3. No Implicit Vocabulary

Core assigns no registered product meaning to values such as:

[+ priority:high]
[! security]
[^ legal text]
[:temperature = 21.5]

A product may define these conventions separately. Another product may preserve the same AST while presenting it differently or taking no action. Convention identifiers and registries remain outside Core. The optional document/modules convention lets an author identify an independently versioned convention without changing Core grammar or selecting software for the reader.

4. Numbering

Heading [n] and auto_number_list record author intent; Core does not calculate a number. A numbering profile should define participating nodes, sequence scope, restart and nesting rules, formatting and localization, and whether hidden nodes consume a number. Derived numbers belong to a projection, not to the parsed Core AST.

Block and table captions do not participate in Core numbering. Labels such as Figure 1.1, Table 2, or Example A are authored text. A consumer may build an index or validate a house numbering style, but it must not rewrite the caption AST as though a generated label appeared in source. Visible captions supplement rather than replace block-specific accessible names or alternate descriptions.

5. Footnotes

Core distinguishes anonymous definitions, named definitions, and references to already-declared named definitions. Authored IDs are identity keys, not requested display labels. Consumers own sequence scope, displayed numbers or symbols, hover/callout/endnote presentation, placement, backlinks, accessibility phrasing, and repeated-reference behavior. Projection choices must not alter Core reference resolution or imply calculated labels were present in source.

6. Images

Image modes are portable intent rather than exact geometry:

• inline requests alignment at surrounding text height;

• half requests half the source's original height;

• full requests the source's original height.

Consumers define fallbacks when intrinsic height is unavailable. Core performs no file or network access, authentication, byte inspection, or MIME validation. Alt text remains mandatory and should remain available when a source is rejected or fails to load.

The reference HTML renderer's URL filtering and base-resolution option are non-normative projection policy, not additional Core semantics.

7. Links and External Resources

Core distinguishes resolved local #id targets from other link targets. A consumer must apply an allowlist or equivalent navigation policy before activating an external target. Successful parsing does not establish safety, reachability, or trust.

A multi-document publication may use document:id or document:id#anchor as a consumer-owned target convention. Core preserves the target as ordinary link data. A publication processor resolves the document ID against its own catalog, verifies an optional target anchor, and emits a projection- appropriate destination such as a sibling .html or .md artifact. The declaration does not imply network access or introduce a new Core link kind.

[+] may describe a resource in a consumer vocabulary, but it does not acquire implicit navigation behavior and is not a substitute for Core link syntax.

8. Extensions and Execution

Core documents are non-executable. Opaque extension blocks preserve data; they do not authorize evaluation. Interpretation or execution requires an explicit registry and trust policy, validated payloads, isolated effects, and environment permissions.

Unknown extensions, [+] values, and custom datatypes remain preservable data and must not trigger behavior merely by appearing in a valid document.

Semantic wrapper IDs likewise remain inert until a consumer explicitly interprets them. The reference HTML emits no visible label, DOM id, class, or data-* attribute for either form.

9. Graph Extension Convention

The graph extension is a consumer-owned, non-executable graph-description profile. Its payload has one declaration per nonblank line:

+++graph
["resolve", "Resolve", 50, 10]
["bindings", "Binding Set", 50, 20]
{"resolve", "CB", "bindings", "CT", "to", "solid"}
+++ (Figure 1: Resolution graph)
+++fallback
Resolve [>] Binding Set
+++

A square-bracket declaration defines a node as [id, text, x, y]. A brace declaration defines an edge as {fromId, fromPort, toId, toPort, direction, stroke}. String fields use JSON string quoting and escaping. Node IDs use the shared v2 identifier grammar, are case-sensitive, and must be unique within the graph. Edge references may be forward references but must all resolve after the complete payload has been read.

Coordinates are finite numbers from 0 through 100 and identify the node centre on a normalized layout plane. A renderer calculates node dimensions from plain-text labels, fits its visible viewport to the occupied graph bounds, and adds outer padding so boundary nodes, strokes, and arrowheads are not clipped. The normalized layout plane does not require a permanently fixed-size canvas. \n in a label requests a line break.

Ports form a closed nine-value set:

LT CT RT
LC CC RC
LB CB RB

The first character is horizontal position and the second is vertical position. Edge direction is one of none, to, from, or both; stroke is solid or dashed. to places an arrowhead at the toId end and from places one at the fromId end. Edges are painted behind nodes in source order.

Malformed payload is a graph-profile diagnostic, not a Core parse failure. A consumer without an explicitly configured compatible renderer uses the adjacent fallback. Published documents should provide a fallback so Markdown, accessibility tools, and unaware consumers retain the graph's meaning. A v2 closer caption supplies the visible figure description independently of the SVG accessibility title and remains available when the fallback is projected.

10. EBNF Railroad Enhancement

A consumer may progressively enhance an ordinary captioned ebnf code block into a railroad diagram. The code remains the portable representation and fallback; this convention introduces no extension block or module dependency. Canonical specification sources begin each production with Name ::= expression, omit a trailing semicolon, and indent any continued expression lines. Quoted strings are terminals; identifiers are non-terminals. Whitespace or a comma sequences terms, | selects alternatives, square brackets make a term optional, and braces repeat a term zero or more times. Postfix ?, *, and + express optional, zero-or-more, and one-or-more repetition. Parentheses group an expression, ε represents an empty path, quoted single-character ranges use "A".."Z", and ? descriptive terminal ? represents a lexical condition that is clearer in prose than as structural productions.

The renderer distinguishes terminals from non-terminals and gives alternatives, optional paths, and repetitions dedicated tracks. If the EBNF cannot be interpreted by the enhancement profile, the consumer leaves the original code block visible. Unaware consumers and Markdown projections likewise retain the source as an ordinary ebnf code block. A compatibility reader may additionally accept legacy = production operators, trailing semicolons, and production names split from their operators, but canonical specification sources do not emit those forms.

11. Document Module Declaration

A document may formally identify the consumer conventions expected by its extension blocks with one informational declaration:

+++document/modules
dependencies = {
  graph = "org.aeonite.gp.graph.v1"
}
+++

Under this consumer convention, document/modules:

• is optional and may occur at most once;

• must be the final top-level block in the Core document;

• must not have a fallback;

• contains an AEON document whose only top-level binding is the dependencies object;

• maps exact extension names to independently versioned module-convention identifiers;

• is metadata and does not produce visible document content.

An extension name containing characters that cannot form a bare AEON key, such as chart/pie, is written as a quoted AEON key. A module-convention identifier uses reverse-domain-style lowercase segments and ends in .v followed by digits. It is an identity string, not a package coordinate, URL, import path, or executable name.

The declaration is purely informational. Its presence MUST NOT initiate installation, dependency resolution, network access, code loading, execution, or a permission prompt. A consumer may compare it only with convention implementations already selected through that consumer's trusted configuration. An unknown, unavailable, or disallowed convention leaves the extension opaque and causes its fallback to be used. Absence of a declaration does not make an otherwise valid Core extension block invalid.

Core continues to parse document/modules as an ordinary opaque extension_block. Final-block placement and AEON payload validation are consumer-convention rules applied only after Core parsing.

12. Standalone Publication Projection

A publication consumer may combine an external publication envelope and its embedded document into a standalone .and projection. The projection begins with &ND v2, followed by one leading +++document/meta block. The metadata block has no fallback, contains an AEON document, does not produce visible document content, and is followed by the ordinary document blocks. A final +++document/modules declaration retains its final-block position.

The closed metadata record contains schemaVersion, id, title, description, family, group, standing, lifecycle, normativity, license, path, order, publish, keywords, and related. Envelope-only body and bodyFormat fields are omitted because the surrounding file is the body and the leading declaration identifies its format and version.

A human-readable projection may use a preferred line width, conventionally 120, without making that width a validity limit. Ordinary prose wraps only at safe whitespace. A list-item paragraph uses two-space continuation indentation:

- A long list item may wrap onto a continuation line while remaining one
  list-item paragraph.

Tables align to their natural column widths and may exceed the preferred width; they are never cropped or truncated. Code, extension payloads, headings, long resource targets, and other indivisible syntax may likewise exceed it. Top-level headings have two empty source lines before them to make section boundaries visually distinct. [.] remains the only explicit content line break.

A conforming publication formatter reparses its output, validates document/meta against the source envelope, removes that metadata block, and requires the remaining document's canonical form to equal the source document's canonical form. A failed equality check rejects the artifact.

13. Conformance Boundary

Core conformance covers grammar-version acceptance, AST fields, local-anchor integrity, canonical spelling, and requested spans or budgets. A consumer profile covers behavior only after a valid Core parse and must be tested and versioned separately. The inert reference HTML projection demonstrates one safe approach, but its classes, styling, and interactions are not normative Core requirements.