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

2. Choose Format

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

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