dec-0052

Vista generada de dec-0052: Block buffer

ImplementadoSin versión del tren todavía· generada desde docs/decisions/dec-0052-block-buffer.md
track/docsdec-0124track/docs:DC10

Vista generada desde docs/decisions/dec-0052-block-buffer.md. No se edita a mano: bun run docs:gen la regenera y bun run docs:check falla si difiere. El estado aquí es el del model: si discrepa con otra página, manda el model.

CampoValor
EstadoLOCKED (migrado de un rNN por gate-3: el fichero no declara estado)
Referencia legadar40-L1
Ficherodocs/decisions/dec-0052-block-buffer.md

Enmendado o sustituido por: r46, r60, r61

Por qué importa (del frontmatter del ADR):

Código real, no solo cross-cita: native/zig/media-core/source/buffer/zero_copy_buffer.zig implementa exactamente esto (docstring cita 'r40 / TKT-016 M1' línea 1-2, 'BACKING_ALIGN r40 §1' línea 32). Usado en 19 archivos: l1_ram.zig, l2_nvmc.zig, tiered_cache.zig, local_file.zig, cache_soak.zig, quiczig_transport.zig, moqt_publisher/relay/server/subscriber/types/test.zig.

Nodos del roadmap que lo citan en refs: ninguno.

Páginas de la documentación que lo citan: ninguna todavía.

Texto del ADR

Leído de docs/decisions/dec-0052-block-buffer.md, el fichero canónico.

Block buffer

Block buffer: single-allocation page-aligned + refcount atómico + zero-copy fanout (TAKE from MoQ FrameBuf)

Por qué pasa gate-3

  • Hard-to-reverse: Una vez que toda la arquitectura está basada en este patrón de refcount atómico + single-allocation, revertirlo requeriría reescribir el core del media cache y scheduler del daemon Zig. No es un flip de config.
  • Surprising sin contexto: Un ingeniero competente viendo Arc<FrameBufInner>-style o punteros Zig con refcount atómico NO inferiría POR QUÉ se eligió este patrón específico sin el contexto del harvest MoQ y la comparación explícita con MediaMTX (closure Go vs refcount atómico). Parecería un overengineering sin el ADR.
  • Trade-off real: Alternativa rechazada explícita: MediaMTX closure Go (presión GC, overhead runtime). El trade-off es complejidad manual de lifetimes (refcount atómico, defer/errdefer) vs presión de GC y overhead de copias. Se eligió el patrón Rust/Zig zero-copy por control explícito y performance.

Procedencia

Split de docs/decisions/r40-scheduler-cache-mechanics-harvest-2026-06-30.md (lock r40-L1) durante PASO 7 (2026-07-16). Ver el fichero padre para el contexto completo del pack original.

dec-0051

Vista generada de dec-0051: M1 (F0.C.1) scope

dec-0053

Vista generada de dec-0053: Backpressure waker-based segmentado, NUNCA polling (ADAPT from MoQ kio + iroh-live)

Texto del ADR
Block buffer
Por qué pasa gate-3
Procedencia