feat(types): Echo types (structured loss) across the pipeline (#17)

Adds Echo<A,B> / EchoR<A,B> as Error-Lang's first-class visible structured-loss
shape, porting the echo-types (Agda) / EchoTypes.jl (Julia) lineage.

Governing invariant: decomposition must be visible — echo_to_residue is never
a silent cast, EchoR never unifies with Echo, and the stability debit is never
hidden.

Compiler: TyEcho/TyEchoR in type checker, VEcho/VResidue in VM/Bytecode,
dedicated opcodes in Codegen, echoEraseCost=15.0 [Stab-Erase] debit.
Five builtins mirror EchoTypes.jl: echo, echo_to_residue, echo_input,
echo_output, residue_strictly_loses.

Tests: three decomposition planes (syntactic, semantic/runtime, type-checking).
Docs: spec/type-system.md §7, docs/Echo-Decomposition.adoc, Curriculum Lesson 11,
EXPLAINME.adoc, contractiles/ (Mustfile, Dustfile, Trustfile.hs, Intentfile),
manifests (STATE, META ADR-0001, NEUROSYM rules, ECOSYSTEM, AGENTIC constraint).

Author: hyperpolymath

.machine_readable/6a2/AGENTIC.a2ml

@@ -20,6 +20,11 @@ can-create-files = true
 # - Never use banned languages (TypeScript, Python, Go, etc.)
 # - Never place state files in repository root (must be in .machine_readable/)
 # - Never use AGPL license (use MPL-2.0)
+# - Never break VISIBLE DECOMPOSITION for Echo types:
+#     * do not make echo_to_residue a silent cast
+#     * do not let EchoR<A,B> behave like / coerce to Echo<A,B>
+#     * do not hide the erasure stability debit ([Stab-Erase])
+#   (see docs/Echo-Decomposition.adoc, spec/type-system.md §7)
 
 [maintenance-integrity]
 fail-closed = true

.machine_readable/6a2/ECOSYSTEM.a2ml

@@ -8,13 +8,17 @@ last-updated = "2026-04-11"
 
 [project]
 name = "Error Lang"
-purpose = ""
-role = ""
+purpose = "A dissembling/decompositional educational language that makes the decay and structured loss of programs, semantics, and types VISIBLE."
+role = "Operational, stability-aware embedding of the Echo (structured-loss) lineage; the decomposition-visible member of the Echo family."
 
 [position-in-ecosystem]
-category = ""
+category = "educational-programming-language"
 
 [related-projects]
 projects = [
-  # No related projects recorded
+  # The Echo (structured-loss) lineage that Error-Lang's Echo<A,B>/EchoR<A,B> embed.
+  # Error-Lang stays Error-Lang-specific (visible decomposition); it does not
+  # re-export these repos' exposition.
+  { name = "echo-types", owner = "hyperpolymath", role = "source of mechanized truth (Agda): Echo f y := Σ(x:A), (f x ≡ y)" },
+  { name = "EchoTypes.jl", owner = "hyperpolymath", role = "finite-domain executable model (Julia) — a model, not a proof" },
 ]

.machine_readable/6a2/META.a2ml

@@ -12,7 +12,15 @@ author = "Jonathan D.A. Jewell (hyperpolymath)"
 
 [architecture-decisions]
 decisions = [
-  # No ADRs recorded
+  # ADR-0001: Echo types model structured loss as first-class, VISIBLE decomposition.
+  #   Echo<A,B> = retained witness + visible output; EchoR<A,B> = residue after
+  #   irreversible erasure; echo_to_residue is an explicit decomposition step that
+  #   debits stability ([Stab-Erase]). Invariant: decomposition must be visible —
+  #   no silent cast, EchoR is not Echo-with-a-missing-field, debit not hidden.
+  #   Runtime is single-witness (VEcho{input,output} / VResidue{output}); whole-fibre
+  #   waits for first-class functions. Builtin names mirror EchoTypes.jl.
+  #   Refs: docs/Echo-Decomposition.adoc, spec/type-system.md §7.
+  { id = "ADR-0001", title = "Echo types as visible structured-loss decomposition", status = "accepted" },
 ]
 
 [development-practices]

.machine_readable/6a2/NEUROSYM.a2ml

@@ -14,6 +14,16 @@ report-format = "logtalk"
 [symbolic-rules]
 # Custom symbolic rules for this project
 # - { name = "no-unsafe-ffi", pattern = "believe_me|unsafeCoerce", severity = "critical" }
+#
+# Echo decomposition must remain VISIBLE (see docs/Echo-Decomposition.adoc):
+#   - echo_to_residue must debit stability — it is never a silent cast
+#   - EchoR<A,B> must not unify with / be coerced to Echo<A,B>
+#   - echo_input must be rejected on a residue (the witness is gone)
+rules = [
+  { name = "echo-erasure-must-cost", concern = "echo_to_residue must apply the [Stab-Erase] stability debit", severity = "high" },
+  { name = "echo-residue-no-coercion", concern = "no implicit Echo->EchoR or Echo->B coercion; EchoR does not unify back into Echo", severity = "high" },
+  { name = "echo-input-not-on-residue", concern = "echo_input is illegal on EchoR (non-recoverable residue)", severity = "high" },
+]
 
 [neural-config]
 # Neural pattern detection settings

.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,67 +1,137 @@
 # 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
 
 project: error-lang
 type: programming-language
 owner: hyperpolymath
 description: >
-  Error-first programming language with graduated error levels and ReScript playground compiler.
+  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. 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)
+
+Error-Lang is not merely "a language with errors." It is decompositional:
+the distinctive claim is that decomposition is itself something the language
+exposes and reasons about. Echo types make STRUCTURED LOSS first-class:
+  - Echo<A, B>        retained witness + visible output (a fibre witness)
+  - EchoR<A, B>       residue after irreversible erasure (witness gone)
+  - echo_to_residue   explicit decomposition step; debits stability ([Stab-Erase])
+Governing invariant: DECOMPOSITION MUST BE VISIBLE — echo_to_residue is never a
+silent cast, EchoR is never an Echo with a missing field, and the stability
+debit is never hidden. See docs/Echo-Decomposition.adoc and spec/type-system.md §7.
+
 ## Critical Invariants
 
+- 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)
 
-## Taxonomy Index
+### 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
 
-- `spec/grammar.ebnf` — @taxonomy: spec/grammar
+### 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
 
-- `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
+### 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/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)