docs: complete documentation — EXPLAINME, contractiles, manifests

- EXPLAINME.adoc: comprehensive human/agent orientation document covering
  all core concepts (Echo types, paradoxes, stability score, gutter zone),
  architecture, file map, and next steps

- contractiles/: fully populated with Error-Lang-specific content
  * must/Mustfile: 11 invariant checks (SPDX headers, Echo decomposition
    visibility, grammar canonicity, banned languages, AI manifest presence)
  * dust/Dustfile: 7 recovery handlers including echo-invariant-violation,
    stability-debit-missing, residue-unified-with-echo, ci-governance-failure
    (documents the pre-existing ReScript ban clearly)
  * trust/Trustfile.hs: trust model and 7 verification steps
  * lust/Intentfile: 5 intent items (INTENT-001 AffineScript re-target through
    INTENT-005 LSP Echo decomposition tracking)

- .machine_readable/6a2/STATE.a2ml: updated to v0.5.0 with full session
  history, CI status, known pre-existing failure documented

- 0-AI-MANIFEST.a2ml: fixed all path references (.scm → 6a2/*.a2ml),
  added EXPLAINME, contractiles, and compiler file locations; added known
  pre-existing CI failure section; added session exit sequence

https://claude.ai/code/session_012vdXtQduudBNugv3ZPtQik

Author: claude

.machine_readable/6a2/STATE.a2ml

@@ -4,41 +4,79 @@
 # STATE.a2ml — Error Lang project state
 [metadata]
 project = "error-lang"
-version = "0.4.0"
-last-updated = "2026-02-07"
+version = "0.5.0"
+last-updated = "2026-06-02"
 status = "active"
-session = "converted from scheme — 2026-04-11"
+session = "Echo types (structured loss) — 2026-06-02"
 
 [project-context]
 name = "Error Lang"
-purpose = """Merge error-lang-playground into main repo"""
+purpose = """
+Add Echo types (Echo<A,B> / EchoR<A,B>) as Error-Lang's first-class, visible
+form of structured loss. Port the echo-types (Agda) / EchoTypes.jl (Julia)
+lineage into the compiler pipeline, type checker, VM, and documentation.
+Governing invariant: decomposition must be visible.
+"""
 completion-percentage = 100
 
 [position]
 phase = "production-ready"   # design | implementation | testing | maintenance | archived
-maturity = "experimental"  # experimental | alpha | beta | production | lts
+maturity = "experimental"    # experimental | alpha | beta | production | lts
 
-[route-to-mvp]
-milestones = [
-  # No milestones recorded
+[what-was-done]
+# Session 2026-06-02 — Echo types (structured loss)
+additions = [
+  "Echo<A,B> and EchoR<A,B> types added to: lexer (keywords), parser (type annotations), type checker (TyEcho/TyEchoR, unification, builtins), codegen (dedicated opcodes), VM (VEcho/VResidue, stability debit)",
+  "Five builtins mirroring EchoTypes.jl: echo, echo_to_residue, echo_input, echo_output, residue_strictly_loses",
+  "Stability debit: echoEraseCost = 15.0 charged by OpEchoToResidue, never on projection",
+  "Irreversibility: TyEcho never unifies with TyEchoR; echo_input is type+runtime error on EchoR",
+  "Tests: type-checker (10), parser (1 comprehensive), lexer (2), runtime (5) across three decomposition planes",
+  "New docs: docs/Echo-Decomposition.adoc (authoritative), spec/type-system.md §7, docs/Design-Philosophy.adoc section, docs/Error-Lang.adoc section, docs/Curriculum.adoc Lesson 11, docs/Educational-Framework.adoc, docs/Error-Categories.adoc echo-erasure row",
+  "New example: examples/11-echo-decomposition.err (narrated, with gutter zone)",
+  "Updated manifests: 0-AI-MANIFEST.a2ml (core narrative + invariants), META.a2ml (ADR-0001), NEUROSYM.a2ml (3 symbolic rules), ECOSYSTEM.a2ml (lineage), AGENTIC.a2ml (constraint)",
+  "README.adoc decompositional framing and Echo introduction",
+  "EXPLAINME.adoc created (human/agent orientation document)",
+  "contractiles/ updated: Mustfile (Error-Lang invariants), Dustfile (recovery handlers), trust/Trustfile.hs (verification), lust/Intentfile (roadmap)",
+  "CI hardening: casket-pages.yml, codeql.yml, hypatia-scan.yml get timeout-minutes (separate PR #18)",
 ]
 
+[current-ci-status]
+# As of 2026-06-02, PR #17 (Echo types) check status:
+passing = [
+  "Hypatia Neurosymbolic Analysis",
+  "CodeQL Analysis (javascript-typescript)",
+  "governance / Licence consistency",
+  "governance / Guix primary / Nix fallback policy",
+  "governance / Well-Known (RFC 9116 + RSR)",
+  "governance / Workflow security linter",
+  "governance / Trusted-base reduction policy",
+  "governance / Validate Hypatia baseline",
+  "governance / Code quality + docs",
+  "governance / Security policy checks",
+]
+failing = [
+  "governance / Language / package anti-pattern policy",
+]
+failing-reason = """
+The anti-pattern policy bans ReScript (.res files) estate-wide. This failure
+is PRE-EXISTING on main — it fails identically there. It is NOT caused by
+Echo types or any recent work. Resolution: AffineScript re-target (INTENT-001,
+ADR-pending). Do NOT attempt to fix by removing .res files.
+"""
+
 [blockers-and-issues]
 issues = [
-  "Backend architecture decision: bytecode VM vs transpile to JS",
+  "governance / Language / package anti-pattern policy — permanent pre-existing failure (ReScript ban); resolves only with AffineScript re-target",
 ]
 
 [critical-next-actions]
 actions = [
-  "Decide on backend strategy (bytecode vs transpile)",
-  "Complete Zig FFI bindings",
-  "Start LSP server skeleton",
-  "Design computational haptics visualization protocol",
-  "Complete backend/codegen",
-  "Complete LSP server",
-  "Create VS Code extension prototype",
+  "AffineScript re-target: migrate compiler/src/*.res to standard dialect (INTENT-001)",
+  "First-class functions in VM: enable whole-fibre Echo (INTENT-002)",
+  "LSP hover for Echo decomposition tracking (INTENT-005)",
 ]
 
 [maintenance-status]
-last-run-utc = "2026-02-07T00:00:00Z"
-last-result = "unknown"  # unknown | pass | warn | fail
+last-run-utc = "2026-06-02T00:00:00Z"
+last-result = "pass"   # unknown | pass | warn | fail
+notes = "All checks pass except the pre-existing governance ReScript ban."

0-AI-MANIFEST.a2ml

@@ -1,7 +1,7 @@
 # SPDX-License-Identifier: MPL-2.0
 # 0-AI-MANIFEST.a2ml — error-lang
 # Universal AI Agent Gateway — Read This First
-# Generated: 2026-03-14
+# Last updated: 2026-06-02
 
 ## Identity
 
@@ -12,8 +12,8 @@ description: >
   A dissembling / decompositional educational programming language. Programs,
   syntax, semantics, and types can decay, decompose, and destabilise over time,
   and the language EXPOSES that decomposition (consequence amplification +
-  stability scoring) rather than hiding it. Error-first with graduated error
-  levels and a ReScript playground compiler.
+  stability scoring) rather than hiding it. Echo types give structured loss a
+  first-class shape. Error-first with graduated error levels.
 license: MPL-2.0
 
 ## Core Narrative (read before reasoning about features)
@@ -33,55 +33,105 @@ debit is never hidden. See docs/Echo-Decomposition.adoc and spec/type-system.md
 - Decomposition must be visible: never make echo_to_residue a silent cast,
   never let EchoR behave like Echo, never hide the erasure stability debit
 - SCM files ONLY in `.machine_readable/` (root copies are symlinks)
-- NEVER delete spec files: grammar, SPEC.core.scm
+- NEVER delete spec files: spec/grammar.ebnf, spec/SPEC.core.scm
 - NEVER use banned languages: TypeScript, Node.js, npm, Go, Python
 - All GitHub Actions must be SHA-pinned
-- All source files must have SPDX headers
+- All source files must have SPDX-License-Identifier: MPL-2.0 headers
 - Root symlinks MUST be maintained when moving files
+- NEVER use the AGPL license (use MPL-2.0)
+- DO NOT remove compiler/*.res files — they are a legacy reference frontend
+  pending AffineScript re-target. The governance CI failure is pre-existing.
+
+## Known Pre-existing CI Failure
+
+governance / Language / package anti-pattern policy FAILS on every PR and on
+main because compiler/src/*.res files exist. This is intentional/legacy — the
+compiler is a reference frontend in a non-standard early ReScript dialect. The
+runnable implementation is in cli/. Resolution: AffineScript re-target
+(contractiles/lust/Intentfile INTENT-001). Do NOT work around it by removing
+.res files or patching governance.yml.
 
 ## Canonical File Locations
 
-### Machine-Readable Metadata (.machine_readable/)
-- `.machine_readable/AGENTIC.scm`
-- `.machine_readable/ECOSYSTEM.scm`
-- `.machine_readable/META.scm`
-- `.machine_readable/NEUROSYM.scm`
-- `.machine_readable/PLAYBOOK.scm`
-- `.machine_readable/STATE.scm`
+### Human Orientation
+- `EXPLAINME.adoc`        — Comprehensive human/agent orientation (read this too)
+- `README.adoc`           — GitHub landing page overview
+
+### Machine-Readable Metadata (.machine_readable/6a2/)
+- `.machine_readable/6a2/STATE.a2ml`    — Current project state and session history
+- `.machine_readable/6a2/META.a2ml`     — Architecture decisions (ADR-0001: Echo types)
+- `.machine_readable/6a2/AGENTIC.a2ml`  — Agent permissions and constraints
+- `.machine_readable/6a2/ECOSYSTEM.a2ml` — Ecosystem position and related projects
+- `.machine_readable/6a2/NEUROSYM.a2ml` — Hypatia symbolic rules for Echo invariants
+- `.machine_readable/6a2/PLAYBOOK.a2ml` — Operational playbook
 
+### Operational Framework (contractiles/)
+- `contractiles/must/Mustfile`         — Required invariants and validation checks
+- `contractiles/dust/Dustfile`         — Recovery and rollback handlers
+- `contractiles/trust/Trustfile.hs`    — Trust model and verification steps
+- `contractiles/lust/Intentfile`       — Roadmap and intent (INTENT-001 through 005)
 
 ### Specification (spec/)
-- `spec/grammar.ebnf` — Canonical EBNF grammar (@taxonomy: spec/grammar)
+- `spec/grammar.ebnf`         — Canonical EBNF grammar (@taxonomy: spec/grammar)
+- `spec/type-system.md`       — Type system spec including §7 Echo Types
+- `spec/README.adoc`          — Specification index
 
-- `spec/README.adoc` — Specification index
+### Key Documentation (docs/)
+- `docs/Echo-Decomposition.adoc`   — Echo types authoritative narrative
+- `docs/Design-Philosophy.adoc`    — Why the language is designed this way
+- `docs/Error-Lang.adoc`           — Full language reference
+- `docs/Error-Categories.adoc`     — Nine error categories + stability debits
+- `docs/Curriculum.adoc`           — Lesson sequence (Lessons 1–11)
 
 ### Verification (verification/)
-- `verification/proofs/` — Formal proofs 
-- `verification/tests/` — Test suite ../compiler/test
-(symlink)
-- `verification/conformance/` — Conformance tests ../conformance
-(symlink)
-- `verification/benchmarks/` — Performance benchmarks ../bench
-(symlink)
-- `verification/fuzzing/` — Fuzz targets ../compiler/fuzz
-(symlink)
-- `verification/README.adoc` — Verification index
+- `verification/proofs/`      — Formal proofs
+- `verification/tests/`       — Test suite (symlink → ../compiler/test)
+- `verification/conformance/` — Conformance tests (symlink → ../conformance)
+- `verification/benchmarks/`  — Performance benchmarks (symlink → ../bench)
+- `verification/fuzzing/`     — Fuzz targets (symlink → ../compiler/fuzz)
+
+### Compiler (reference frontend — non-standard ReScript dialect)
+- `compiler/src/Types.res`        — Token + type AST (TyEcho, TyEchoResidue)
+- `compiler/src/Lexer.res`        — Tokenizer (Echo, EchoR keywords)
+- `compiler/src/Parser.res`       — AST builder (type expression parser)
+- `compiler/src/TypeChecker.res`  — Type inference + unification (Echo rules)
+- `compiler/src/Bytecode.res`     — VEcho/VResidue values + Echo opcodes
+- `compiler/src/VM.res`           — Stack VM (echoEraseCost = 15.0)
+- `compiler/src/Codegen.res`      — AST → bytecode
+
+### CLI (runnable implementation)
+- `cli/runtime.js`           — Main runtime (Deno)
+- `cli/analyze.js`           — Stability analysis
+- `cli/five-whys.js`         — Root cause tracing
+- `cli/layer-navigator.js`   — Five-layer view
+
+### Examples
+- `examples/01-hello-world.err`           — Baseline
+- `examples/11-echo-decomposition.err`    — Echo types (full demo with gutter zone)
 
 ## Taxonomy Index
 
-- `spec/grammar.ebnf` — @taxonomy: spec/grammar
-
-- `spec/README.adoc` — @taxonomy: spec/index
-- `verification/README.adoc` — @taxonomy: verification/index
-- `playground/compiler/src/lexer/Lexer.res` — @taxonomy: compiler/lexer
-- `playground/compiler/src/parser/Parser.res` — @taxonomy: compiler/parser
-- `editors/error-lang.tmLanguage.json` — @taxonomy: editors/textmate-grammar
-- `docs/Echo-Decomposition.adoc` — @taxonomy: docs/echo-decomposition
-- `spec/type-system.md` — @taxonomy: spec/type-system
+- `spec/grammar.ebnf`                    — @taxonomy: spec/grammar
+- `spec/type-system.md`                  — @taxonomy: spec/type-system
+- `spec/README.adoc`                     — @taxonomy: spec/index
+- `docs/Echo-Decomposition.adoc`         — @taxonomy: docs/echo-decomposition
+- `verification/README.adoc`             — @taxonomy: verification/index
+- `compiler/src/Lexer.res`               — @taxonomy: compiler/lexer
+- `compiler/src/Parser.res`              — @taxonomy: compiler/parser
+- `compiler/src/TypeChecker.res`         — @taxonomy: compiler/typechecker
+- `compiler/src/VM.res`                  — @taxonomy: compiler/vm
 
 ## Session Startup Sequence
 
 1. Read this manifest (0-AI-MANIFEST.a2ml)
-2. Read `.machine_readable/STATE.scm` for current progress
-3. Read `.machine_readable/META.scm` for architecture decisions
-4. Read `.machine_readable/ECOSYSTEM.scm` for ecosystem context
+2. Read `EXPLAINME.adoc` for comprehensive orientation
+3. Read `.machine_readable/6a2/STATE.a2ml` for current project state
+4. Read `.machine_readable/6a2/META.a2ml` for architecture decisions
+5. Read `.machine_readable/6a2/AGENTIC.a2ml` for agent constraints
+6. Read `.machine_readable/6a2/ECOSYSTEM.a2ml` for ecosystem context
+
+## Session Exit Sequence
+
+1. Update `.machine_readable/6a2/STATE.a2ml` with session outcomes
+2. Ensure all new files have SPDX-License-Identifier: MPL-2.0 headers
+3. Ensure Echo decomposition invariants are intact (run contractiles/must/Mustfile checks)