Yon write

/yon-write

YON Writing & Compilation Mode — create, generate, or convert content into YON (YounndAI Object Notation), a line-oriented, stream-first Cognitive Architecture for AI systems.

The Encoding Principle

Foundational contract: YON preserves what the emitter wants to send. An encoder preserves what was said. A translator decides what was meant. YON is an encoder.

• "probably purple" stays "probably purple" — do not resolve to confidence: 0.6
• "like everyone else does" stays verbatim — do not interpret vague social references
• Hedging, uncertainty, and conversational nuance are preserved exactly
• Links, paths, URLs are preserved byte-for-byte. Never alias, shorten, or rewrite.
• The human's intent is sovereign. The encoding layer is faithful to the source. Interpretation is downstream.

When NOT to Generate YON

YON is a Cognitive Architecture for AI pipelines, not a universal data format. Do not use it for:

• API responses — YON adds +54–185% size vs JSON minified for pure data payloads
• Config files — TOML or YAML are better for human-edited configuration
• Short messages under ~340 tokens — plain text is cheaper at small context sizes
• Database records — use JSON, Protobuf, or native formats
• Simple key-value data — YON's structural baseline adds no benefit for flat data

YON belongs in: system prompts, agent instructions, multi-hop pipelines, rules/policies, workflows, cognitive traces, provenance tracking, and anywhere intent + data + audit travel together.

Decision Gate — Before You Write

1. Choose Profile

Profile	Use When
core	Basic structure (docs, notes)
decl	Rules and schemas (policies, configs)
exec	Workflows (steps, checks, error handling)
audit	Provenance tracking
cognitive	AI thought chains
agent	Multi-agent systems

2. Choose Format

Format	Use Case
canon	Human docs, reference material
min	LLM pipelines, agents (recommended default)
ultra	Cost-critical transport

3. Choose Kind

doc, rule, workflow, skill, sidecar, spec, context, memory, note, prompt

Output Rules

When writing to a .yon file: Output YON records ONLY. No markdown, no fenced blocks, no commentary. Pure YON.

When showing YON in conversation: Use a fenced code block and briefly explain your choices (profile, kind, key decisions made during encoding).

Always:

• First non-comment line MUST be @DOC
• Separator: ALWAYS | (space, pipe, space)
• Bare values when matching [A-Za-z0-9_./:@+#-]+, otherwise double-quote
• Values containing | MUST be quoted: regex="a|b|c"
• Typed keys for non-strings: n:int=3, active:bool=true, ts:ts=2026-01-01T00:00:00Z
• @MAP pairs: BOTH sides quoted: pairs=["key"->"value"]
• @BEGIN/@END blocks: mime= required, boundary= 8+ chars, id= required when multiple blocks or referenced
• Self-describing docs: add guide="https://yon.younndai.com/yon-guide.txt" when the document targets LLMs without YON knowledge

Required Fields Per Tag

Tag	Required Fields
@DOC	ver, id, title
@SEC	name
@NOTE	text
@STAMP	ts, src
@RULE	lvl (MUST/MUST_NOT/SHOULD/SHOULD_NOT/MAY), when, then
@MAP	name, pairs
@CFG	id, set
@INTENT	goal
@CHECK	rid, assert, fail (ABORT/WARN/SKIP), msg
@STEP	rid, n:int, op
@CATCH	target, on, do
@RETRY	target, max
@PATCH	ts, target, set
@VOID	ts, target
@REDACTION	target, reason
@CONSENT	party, scope

Conversion Patterns

Prose → Rules

• "Always" / "Must" → lvl=MUST
• "Never" / "Must not" → lvl=MUST_NOT
• "Prefer" / "Should" → lvl=SHOULD
• "Optional" / "May" → lvl=MAY

Tables → Schema / Map / Cfg

• Enum/Choices → @SCHEMA key=severity | opts=[low,med,high] | default=med
• Condition→Outcome → @MAP pairs=["input"->"output"]
• Multi-setting → @CFG id=X | set=[k=v] then @MAP pairs=["ctx"->"cfg:X"]

Code/JSON/Logs → Blocks

@BEGIN CODE | id=handler | mime="text/x-python" | boundary="bnd_py_001"
def hello():
    return "world"
@END CODE | boundary="bnd_py_001"

List Constraints

• in/out: reference tokens ONLY (block:, rid:, cfg:, ref:, file:, url:, agent:, etc.)
• args/set: field items ONLY (key=value, key:type=value)
• pairs: map pairs ONLY ("k"->"v")
• Depth limit = 1. No nested lists.

Worked Example: Prose → YON

Input (user's messy prose):

"ok so we need an api rate limiting thing. all calls must have auth tokens. standard users get 100/min, premium 500. if they hit the limit they should probably back off exponentially. never expose internal errors in responses."

Output:

@DOC ver=2.0 | id=api-rate-policy | title="API Rate Limiting Policy" | kind=rule | profile=decl | fmt=min
@INTENT goal="Define authentication and rate limiting standards for public API"

@SEC name="Authentication"
@RULE rid=rule:auth | lvl=MUST | when="calling any API endpoint" | then="include valid auth token"

@SEC name="Rate Limits"
@MAP name=TierLimits | pairs=["standard"->"100/min","premium"->"500/min"]
@RULE rid=rule:backoff | lvl=SHOULD | when="rate limit exceeded" | then="probably back off exponentially"

@SEC name="Error Handling"
@RULE rid=rule:errors | lvl=MUST_NOT | when="returning API response" | then="expose internal error details"

@STAMP ts:ts=2026-03-30T12:00:00Z | src=human

What the encoding did: Detected section boundaries from topic shifts. "must" → MUST, "never" → MUST_NOT, "should probably" → SHOULD. Preserved "probably back off exponentially" verbatim (hedging preserved). Dropped "ok so" and "thing" (zero semantic content).

What the encoding did NOT do: Did not resolve "probably" into a confidence level. Did not reorder the user's sequence. Did not add fields the user didn't mention.

Handling Ambiguous Input

When the input doesn't map cleanly to YON:

• Unclear when/then split: Use a broad when (e.g., when="in all contexts") and put the action in then. Don't fabricate conditions.
• Mixed intent and data: Put purpose in @INTENT, constraints in @RULE, factual descriptions in @NOTE. When unsure, @NOTE is the safe default.
• Vague severity: Default to SHOULD and flag with note="severity inferred — confirm with author"
• Nested/complex structures: Flatten. Use @CFG for grouped settings, @BEGIN/@END blocks for verbatim payloads. Depth limit is 1.

Validation Checklist

After writing, verify:

• Exactly one @DOC, first non-comment record
• All @BEGIN have matching @END with same TAG and boundary
• All @BEGIN include mime=
• No duplicate keys within a single record
• @MAP uses pairs=[...] with both sides quoted
• Canonical separator | used consistently
• All required fields present for each tag
• @RULE with lvl=MUST or MUST_NOT are individual records (never merged/summarized)

Record Order (Recommended)

@DOC → @STAMP → @META → @DEF → @REF → @INTENT → @SCOPE → @SEC sections → @BEGIN/@END blocks

Detailed References

For edge cases, extended syntax, and complete examples:

• references/write-card.txt — Complete compilation reference card with one-shot examples
• references/domains-card.txt — All profiles, formats, kinds, and official domain list
• references/generation-guide.md — Comprehensive examples: rules, workflows, cognitive traces, multi-agent, prose encoding

Full spec: https://yon.younndai.com