# Decorator-as-seam — IMPLEMENTED + PROVEN ON CLONE (2026-08-14)

> **UPDATE — no longer staged. The boundary auto-emit is BUILT and PROVEN on the
> clone.** Will waived the diff review. Implemented: `engram_boundary_beat()` in
> `lang/runtime/el_runtime.c` (afferent counter++, `engram_chrono_tick`,
> `engram_strengthen(self-anchor)`, `dharma_emit`) + two act-stats counters
> (`aff_boundary_ops`, `dharma_emits`); `cg_fn` in `lang/el-compiler/src/codegen.el`
> injects ONE `engram_boundary_beat(op)` at the entry of every `@manager`/`@accessor`
> fn (via `fn_has_decorator`, so it also fires under `@route @manager` stacking).
> Rebuilt `elc` self-host + the **cognition engram** in the worktree; ran it as the
> clone daemon on `:8900`.
>
> **Proof** — `/api/boundary-proof` (`@manager`, body = one `return`, ZERO
> instrumentation) called 5×:
> - afferent `aff_boundary_ops` 0→5 · dharma `dharma_emits` 0→5
> - strengthen: self `activation_count` 1510→1513, salience 0.9→1.0
> - chronoception: `chrono_last_tick` 1786760357885→1786760381676
>
> All four auto-fired from the decoration alone; daemon stayed alive; live `:8742`
> untouched. The original staged design is retained below for the record.

---

# Decorator-as-seam — what WAS staged (with the exact diff)

The reshape rests on one idea: **the decorator boundary is the single interception
seam.** Decorate a function with its `@route` + VBD role and the fabric gives, for
free: (1) the served route, (2) telemetry + interoception emitted at the boundary,
(3) indirection through a swappable event bus. Ground-truth of each, with the
minimal change to close the gaps.

## Ground truth (file:line)

| seam | real today? | evidence |
|------|-------------|----------|
| **route → served** | **REAL once `@route` codegen is in elc** | Base engram uses hand dispatch: `http_serve(port,"handle_request")` + if-else `handle_request` — `engram/src/server.el:592,742`. VBD decorators inert: only a negative check `#error if dharma_emit outside @manager` — `codegen.el:2929-2934`; `lang/spec/language.md:449` "decorators with structural meaning today: none". `@route(path,method,kind,suffix)` synthesizes `el_route_dispatch` — `codegen.el:3500-3852` — but only on **unmerged** `feat/el-route-decorators`. **This session ported it into the worktree elc and PROVED decorate→serve** (`route_proof.el` on :8951; `surface.el` compiles, dispatcher generated for all 8 ops). |
| **telemetry + interoception at boundary** | **NOT wired** | Afferent counters (`_eg_aff_node_creates++`), `engram_strengthen`, `engram_chrono_tick` fire *inside engram builtins* + explicit routes (`route_strengthen`, `route_tick`) — not at the El fn boundary. `cg_fn` (`codegen.el:2919`) injects zero instrumentation. |
| **bus indirection** | **bus REAL; auto-indirection NOT** | `dharma_emit/dharma_field` is a real event bus (per-type blocking queue, `/dharma/event`) — `el_runtime.c:11685-11987`. Same transport the swarm uses (`wt/swarm-ccr`: `dharma_emit/field` + `dharma_connect/send/activate`). `@manager` *may* call it (enforced) but decoration does not auto-insert it. `surface.el` calls it explicitly today (correct, compiles). |

## The minimal change — auto-emit at the decorated boundary

Inject a prologue in `cg_fn` (right after the C signature line) keyed on the VBD
role decorator. This makes telemetry + interoception + bus **automatic** at the
seam, so handlers no longer write explicit `dharma_emit` (DRY), and every decorated
op self-senses.

```el
// lang/el-compiler/src/codegen.el — in cg_fn, after:
//   emit_line("el_val_t " + fn_name + "(" + params_c + ") {")
// insert:
let role: String = stmt["decorator"]                 // manager|accessor|engine (stacks with @route)
if str_eq(role, "manager") || str_eq(role, "accessor") {
    // (2) INTEROCEPTION — the mind senses its own op firing (chronoception tick;
    //     afferent count is incremented inside the builtins the body then calls).
    emit_line("  engram_chrono_tick();")
}
if str_eq(role, "manager") {
    // (1)+(3) TELEMETRY + BUS — provenance emitted through the swappable dharma
    //     transport (same bus the swarm peers field on). Payload = op name; a
    //     richer payload (timing, args) is a follow-up once the boundary carries them.
    emit_line("  dharma_emit(EL_STR(\"neuron.op." + fn_name + "\"), EL_STR(\"\"));")
}
```

Rationale for the exact calls:
- `engram_chrono_tick()` — zero-arg, already the interoception primitive
  (`route_tick` → `engram_chrono_tick`); safe to fire per decorated op.
- `dharma_emit(event, payload)` — the real bus (`el_runtime.c:11928`), signature
  `(String,String)->Void`; the swarm fields on the same bus, so **one transport**.
- `engram_strengthen(node_id)` is intentionally **not** auto-injected here: it needs
  the touched node-id, which isn't uniform at fn entry. Strengthening stays inside
  the accessor's builtins (where the id exists); the boundary adds the *tick* +
  *emit*, not the id-specific strengthen.

## Why this is STAGED, not shipped this session

`dharma_emit` / `engram_chrono_tick` / `engram_strengthen` link **only in the
engram+dharma runtime**. A standalone El service (`route_proof.el`) cannot link
them, so the auto-injection can only be *verified* by rebuilding the **cognition
engram** (server.el + the geometry/cognition `el_runtime.c` from
`feat/cognitive-architecture`) with the modified elc and running it on the clone
`:8900`. That rebuild is a multi-branch integration + a delicate ~3.5 MB C build
(AGENTS.md warns of 27 GB OOM on folded builds). Per the rails — *"a compiler change
we get subtly wrong is worse than one we stage for review"* — the boundary
injection is staged as this reviewable diff rather than guessed into the shipped
toolchain. The **route** half of the seam is already proven end-to-end.

## Verification plan (when the boundary injection is approved)

1. Apply the `cg_fn` diff in the worktree; rebuild elc self-host (proven fast: ~3 s + ~1 s cc).
2. Integrate `feat/cognitive-architecture` engram runtime + `surface.el` into the worktree server; build the engram binary with the new elc.
3. Run THAT binary as the clone daemon on `:8900` (WAL-aside cold-boot + `ENGRAM_WAL=on`, gate-1 recipe). Live `:8742` untouched.
4. Drive `neuron.think/attend/learn` and assert: a `neuron.op.*` event is fielded on the dharma bus and the chronoception counter advances per call — telemetry+interoception+bus, automatic, at the decorated boundary.
