THE YAML CONTRACT AS THE SOURCE OF TRUTH: CODE IS REGENERABLE, THE CONTRACT IS NOT
In traditional development, documentation always trails the code. It gets written after the fact, updated late, and eventually lies — because the code evolved and the documentation did not. In AAL, the relationship is inverted: the YAML contract is the source of truth, the code is a consequence of the contract, regenerable at any time by any LLM that receives it. If the code and the contract contradict each other, the code is wrong.
Stack: YAML · Python · any LLM
Reference projects: TeliOs · AAL methodology
Goal: Make code disposable and the contract permanent — the real risk is losing the YAML, not the code
01. THE PROBLEM IT SOLVES
In traditional development, the only real source of truth ends up being the code itself — which is hard to read for anyone who did not write it, and completely opaque to an LLM arriving without context. The result is that every LLM work session starts from scratch, re-explaining what already exists.
The YAML contract eliminates that problem. It precisely defines what each component does, what it exposes, what it depends on, and under what conditions it operates correctly. The LLM receives the contract and generates the code — not the other way around.
// Non-technical explanation
Imagine you build furniture. You have two options: build the chair first and then try to draw the blueprint of what you built, or draw the blueprint first and then build the chair following it. The first option produces blueprints that are always outdated. The second produces blueprints that are always correct because they are the source of the chair. In AAL, the YAML contract is the blueprint. The chair is the code.
02. ANATOMY OF A COMPLETE YAML CONTRACT
A complete contract has five sections: metadata for identity and state, interface for what it exposes, dependencies for what it needs, constraints for non-negotiable limits, and acceptance_tests for verification. The store.js contract is the canonical example from TeliOs.
# Contract for store.js — TeliOs state engine
metadata:
id: TELIO-U001
version: 1.0.0
name: 'TeliOs Store — Global State Engine'
type: utility
status: pending
description: >
Single centralized state for the TeliOs ecosystem.
Persists to localStorage. Notifies changes via events.js.
The only source of truth in the system.
Maximum 100 lines. Zero external dependencies.
language: JavaScript
file: src/store.js
interface:
exports:
getState:
type: function
description: 'Returns the full state or a nested key'
parameters:
key: { type: string, required: false,
description: 'Dot-notation key: kayros.start' }
returns:
type: any
description: 'Value at key, or full state if no key is given'
setState:
type: function
description: 'Updates state, persists to localStorage, emits change event'
parameters:
key: { type: string, required: true }
value: { type: any, required: true }
returns:
type: boolean
description: 'true if saved correctly, false if localStorage failed'
resetModule:
type: function
description: 'Resets a module to its default values'
parameters:
module: { type: string, required: true }
returns:
type: boolean
dependencies:
internal:
- TELIO-U003 # events.js — emits state:changed on every setState
external: {} # ZERO external dependencies — absolute principle
constraints:
quality:
max_lines: 100
test_coverage: '> 80%'
no_dependencies: true
performance:
max_write_time: '< 10ms'
max_state_size: '< 5MB'
behavior:
must_notify: true
must_persist: true
memory_fallback: true
acceptance_tests:
- id: T001
name: 'setState persists to localStorage'
when: "setState('arke.type', 'fire')"
then:
- "localStorage contains TELIOS_STATE key"
- "getState('arke.type') === 'fire'"
- "Events receives emit('state:changed', {key: 'arke.type', value: 'fire'})"
- id: T002
name: 'getState with nested key'
when: "setState('kayros.totalDays', 1096)"
then:
- "getState('kayros.totalDays') === 1096"
- "getState('kayros') is an object with totalDays: 1096"
- id: T003
name: 'memory fallback when localStorage fails'
when: 'localStorage.setItem throws QuotaExceededError'
then:
- "setState returns false"
- "getState keeps working from memory"
- "App does not break"
implementation_notes: >
Use IIFE to encapsulate.
No classes — pure functional module.
DEFAULT_STATE must be defined in full at the top.
Nested keys use dot-notation: 'kayros.start'.
| Section | Content | Purpose |
|---|---|---|
| metadata | ID, version, type, status, description | Unique component identity. The LLM knows what it is and why it exists. |
| interface | Exported functions, parameters, return types | The public contract — what other modules can call. |
| dependencies | Internal (cell IDs), external (libraries) | Dependency graph map. Detects cycles before implementation. |
| constraints | Line limits, performance, behavior rules | Non-negotiable boundaries the LLM cannot ignore. |
| acceptance_tests | When/then scenarios | Objective success criteria. If tests pass, the cell is correct. |
03. USING THE CONTRACT TO GENERATE CODE
The implementation prompt in FocOs does not describe the problem — it delivers the contract directly. The critical instruction is the last one: if the contract and the implementation contradict each other, change the implementation. If the contract has an error, say so before implementing.
PROMPT_IMPLEMENTATION = """
Implement cell {id} of the TeliOs ecosystem.
CONTRACT:
{yaml_content}
ABSOLUTE RULES:
1. Maximum {max_lines} lines
2. Zero external dependencies
3. Implement EXACTLY what is defined in interface.exports
4. Include acceptance tests as // TEST: comments at the end
5. JSDoc on every exported function
The contract is the truth.
If the contract and your implementation contradict — change the implementation.
If the contract has an error — tell me before implementing.
"""
04. REGENERATING A CELL FROM THE CONTRACT
This is the use case that justifies the entire methodology. The code was lost or corrupted — but the YAML contract exists in the repo. That is enough to fully recover it in 15 minutes. Without the contract, the same operation takes hours reconstructing from memory or from broken code.
# The YAML contract exists — that is enough to regenerate
# Recovery workflow:
# 1. Open TELIO-U001.contract.yaml
# 2. Paste content into the implementation prompt
# 3. LLM generates store.js from scratch — conforming to the contract
# 4. Verify acceptance tests T001, T002, T003
# 5. If they pass — cell regenerated. If not — LLM iterates.
# Total time with contract: 10-15 minutes
# Total time without contract: hours or days
An 80-line plain-text YAML file committed to a Git repository is practically impossible to lose. Risk in AAL shifts completely: it is no longer about losing code — it is about losing the contract. And a versioned text file is far easier to protect than a codebase.
-- CONCLUSION
The YAML contract as source of truth solves the deepest problem in LLM-driven development: the fragility of the knowledge base. If the contract exists, the code can be lost, corrupted, or go stale without permanent consequences. The LLM can regenerate it in 15 minutes. This fundamentally changes the nature of risk in development — the risk is no longer losing code. It is losing the contract. And that is much harder to do.
> SYSTEM_READY > NODE_ONLINE