feat: implement DGR-006 tensor bundle boundary

.scratch/distributed-gguf-runtime/evidence/DGR-006/README.md

@@ -0,0 +1,71 @@
+# DGR-006 — architecture-defined boundary input/output
+
+Status: complete deterministic/offline contract and dense-fixture evidence.
+
+## Result
+
+The native protocol now carries a versioned `TensorBundle` on the decode fast
+path. It includes explicit architecture and boundary-point metadata. Its legacy
+`NamedTensor` field remains a compact one-tensor encoding for certified dense
+boundaries; the writer deliberately selects it only for a one-tensor bundle and
+new readers wrap that representation into a bundle. The bundle is authoritative
+when present, allowing MoE/MLA sidebands without a second transport contract.
+
+`architecture_boundary.py` is the fail-closed adapter boundary. Dense head
+Shards accept token IDs and own embedding. Middle/tail Shards accept only a
+validated bundle. Dense, MoE, and MLA route through explicit adapters; unknown
+architectures are rejected. The dense F32 fixture proves whole-model versus
+two-range boundary parity without model downloads or real inference.
+
+Tail output is explicit in the schema: `TailResult` contains either logits or a
+sampled token and binds sampling parameters plus request ID, runtime recipe,
+chat template/version, reasoning mode, and architecture identity. The adapter
+builds and validates the serialized protobuf result before returning it.
+
+## Files changed
+
+- `packages/node/native/proto/shard_runtime.proto`
+- `packages/node/meshnet_node/native_protocol/{codec.py,__init__.py,conformance.py,generated/*}`
+- `packages/node/native/testdata/decode_step_golden.binpb`
+- `packages/node/native/tests/test_shard_protocol_conformance.cpp`
+- `packages/node/meshnet_node/architecture_boundary.py`
+- `tests/test_architecture_boundary.py`
+- `tests/test_native_shard_protocol.py`
+- `packages/node/native/README.md`
+
+## Commands and results
+
+All Python commands used `/run/media/popov/d/DEV/repos/d-popov.com/AI/.venv/bin/python`.
+All native commands used `/run/media/popov/d/DEV/repos/d-popov.com/AI/.venv/bin/cmake`.
+
+```text
+python scripts/generate_native_protocol.py --check       -> passed
+python scripts/generate_protocol_goldens.py --check      -> passed
+pytest -q tests/test_architecture_boundary.py \
+  tests/test_native_shard_protocol.py tests/test_llama_cpp_dependency.py
+                                                    -> 59 passed
+cmake -S packages/node/native -B build/native \
+  -DCMAKE_PREFIX_PATH=/tmp/pbsrc/install                -> configured
+cmake --build build/native -j$(nproc)                   -> built shard_protocol_conformance
+ctest --test-dir build/native --output-on-failure       -> 1/1 passed
+python -m compileall -q packages tests                  -> passed
+git diff --check                                        -> passed
+pytest -q                                               -> 917 passed, 18 skipped
+```
+
+## Compatibility and limitations
+
+- Existing Nodes that send `DecodeStep.tensor` are accepted. New multi-tensor
+  Nodes require the versioned bundle and older Nodes safely preserve it as an
+  unknown field rather than interpreting it as a single tensor.
+- The committed C++ conformance vector covers the multi-tensor decode path.
+- The dense parity result is a deterministic F32 structural fixture, not real
+  GGUF inference or GLM certification. No real inference was run.
+- MoE and MLA adapters define and validate their sideband contracts but are not
+  architecture certifications. DGR-019 owns GLM MoE/MLA/DSA/IndexShare semantics.
+
+## Handoff
+
+DGR-007 can key its Hot KV state to the validated decoded bundle. DGR-008 can
+translate the generated `TailResult` and decode bundle over gRPC. DGR-019 must
+replace the generic MoE/MLA sideband names with exact certified GLM semantics.

.scratch/distributed-gguf-runtime/issues/06-implement-architecture-defined-boundary-input-output.md

@@ -1,6 +1,6 @@
 # 06 — Implement architecture-defined boundary input/output
 
-Status: ready-for-agent
+Status: done
 
 ## Mandatory fresh-session context
 

.scratch/distributed-gguf-runtime/prd.json

@@ -177,7 +177,7 @@
         "Update only this story issue to Status: done after every acceptance criterion and quality gate passes"
       ],
       "priority": 7,
-      "passes": false,
+      "passes": true,
       "notes": "Source issue: .scratch/distributed-gguf-runtime/issues/06-implement-architecture-defined-boundary-input-output.md",
       "dependsOn": [
         "DGR-002",

packages/node/meshnet_node/architecture_boundary.py

@@ -0,0 +1,186 @@
+"""Certified architecture adapters for the public TensorBundle boundary.
+
+The adapter is intentionally small: it owns boundary names and endpoint rules,
+not transformer execution. llama.cpp owns local graphs; callers select a
+certified adapter before accepting an activation from another Shard.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+import struct
+from typing import Callable, Mapping, Sequence
+
+from .native_protocol import (
+    HIDDEN_STATES,
+    ProtocolError,
+    encode_bundle,
+    encode_tensor,
+    pb,
+    validate_tail_result,
+)
+
+
+class Architecture(str, Enum):
+    DENSE = "dense"
+    MOE = "moe"
+    MLA = "mla"
+
+
+class BoundaryStage(str, Enum):
+    HEAD = "head"
+    MIDDLE = "middle"
+    TAIL = "tail"
+
+
+@dataclass(frozen=True)
+class ProtocolIdentity:
+    request_id: str
+    runtime_recipe_digest: str
+    chat_template_id: str
+    chat_template_version: str
+    reasoning_mode: str
+    architecture: Architecture
+
+
+@dataclass(frozen=True)
+class SamplingParameters:
+    temperature: float
+    top_p: float
+    top_k: int
+    seed: int
+
+
+@dataclass(frozen=True)
+class TailOutput:
+    kind: str
+    value: int | object
+
+    @classmethod
+    def sampled_token(cls, token_id: int) -> "TailOutput":
+        if token_id < 0:
+            raise ProtocolError("sampled token id must be non-negative")
+        return cls("sampled_token", token_id)
+
+
+@dataclass(frozen=True)
+class TypedTailResult:
+    identity: ProtocolIdentity
+    sampling: SamplingParameters
+    output_kind: str
+    message: pb.TailResult
+
+    @property
+    def sampled_token_id(self) -> int | None:
+        return self.message.sampled_token_id if self.output_kind == "sampled_token_id" else None
+
+
+@dataclass(frozen=True)
+class ArchitectureBoundaryAdapter:
+    architecture: Architecture
+    required_names: frozenset[str]
+
+    @property
+    def protocol_architecture(self) -> int:
+        return {
+            Architecture.DENSE: pb.ARCHITECTURE_TYPE_DENSE,
+            Architecture.MOE: pb.ARCHITECTURE_TYPE_MOE,
+            Architecture.MLA: pb.ARCHITECTURE_TYPE_MLA,
+        }[self.architecture]
+
+    def bundle_from_token_ids(
+        self,
+        token_ids: Sequence[int],
+        token_embedding: Callable[[int], Sequence[float]],
+    ):
+        """Head-only embedding entry point; middle/tail never receive IDs."""
+        if self.architecture is not Architecture.DENSE:
+            raise ProtocolError("head token embedding is not certified for this architecture")
+        if not token_ids:
+            raise ProtocolError("head requires at least one token id")
+        rows = [tuple(token_embedding(token)) for token in token_ids]
+        if not rows or not rows[0] or any(len(row) != len(rows[0]) for row in rows):
+            raise ProtocolError("token embedding returned inconsistent hidden widths")
+        payload = struct.pack("<" + "f" * (len(rows) * len(rows[0])), *(x for row in rows for x in row))
+        return self.bundle_from_named_payloads({HIDDEN_STATES: payload}, shape=[1, len(rows), len(rows[0])])
+
+    def bundle_from_named_payloads(
+        self, payloads: Mapping[str, bytes], *, shape: Sequence[int] | None = None
+    ):
+        names = set(payloads)
+        if not self.required_names <= names:
+            missing = sorted(self.required_names - names)
+            raise ProtocolError(f"{self.architecture.value} boundary requires {missing}")
+        tensors = []
+        for name, payload in payloads.items():
+            tensor_shape = list(shape) if name == HIDDEN_STATES and shape else [len(payload) // 4]
+            if len(payload) % 4:
+                raise ProtocolError(f"{name!r} F32 fixture payload is not word aligned")
+            tensors.append(encode_tensor(name, payload, tensor_shape, pb.DTYPE_FLOAT32))
+        return encode_bundle(
+            tensors,
+            architecture=self.protocol_architecture,
+            boundary_point="pre_tail_residual",
+        )
+
+    def input_for(self, stage: BoundaryStage, bundle):
+        """Accept architecture state only after the head embedding boundary."""
+        if stage is BoundaryStage.HEAD:
+            raise ProtocolError("head accepts token ids and owns token embedding")
+        if bundle is None:
+            raise ProtocolError(f"{stage.value} requires a TensorBundle")
+        from .native_protocol import decode_bundle
+
+        payloads = decode_bundle(bundle)
+        if bundle.architecture != self.protocol_architecture:
+            raise ProtocolError("boundary architecture does not match certified adapter")
+        if bundle.boundary_point != "pre_tail_residual":
+            raise ProtocolError("unsupported architecture boundary point")
+        if not self.required_names <= set(payloads):
+            raise ProtocolError(f"{self.architecture.value} boundary requires {sorted(self.required_names)}")
+        return bundle
+
+    def tail_result(
+        self, *, identity: ProtocolIdentity, sampling: SamplingParameters, output: TailOutput
+    ) -> TypedTailResult:
+        if identity.architecture is not self.architecture:
+            raise ProtocolError("tail result architecture does not match certified adapter")
+        if not identity.request_id or not identity.runtime_recipe_digest:
+            raise ProtocolError("tail result requires exact request and recipe identity")
+        if output.kind != "sampled_token":
+            raise ProtocolError("uncertified tail output kind")
+        message = pb.TailResult(
+            identity=pb.RequestRecipeIdentity(
+                request_id=identity.request_id,
+                runtime_recipe_digest=identity.runtime_recipe_digest,
+                chat_template_id=identity.chat_template_id,
+                chat_template_version=identity.chat_template_version,
+                reasoning_mode=identity.reasoning_mode,
+                architecture=self.protocol_architecture,
+            ),
+            sampling=pb.SamplingParameters(
+                temperature=sampling.temperature,
+                top_p=sampling.top_p,
+                top_k=sampling.top_k,
+                seed=sampling.seed,
+                greedy=sampling.temperature == 0.0,
+            ),
+            sampled_token_id=int(output.value),
+        )
+        validate_tail_result(message)
+        return TypedTailResult(identity, sampling, "sampled_token_id", message)
+
+
+_ADAPTERS = {
+    Architecture.DENSE: ArchitectureBoundaryAdapter(Architecture.DENSE, frozenset({HIDDEN_STATES})),
+    Architecture.MOE: ArchitectureBoundaryAdapter(Architecture.MOE, frozenset({HIDDEN_STATES, "router_logits"})),
+    Architecture.MLA: ArchitectureBoundaryAdapter(Architecture.MLA, frozenset({HIDDEN_STATES, "mla_position_state"})),
+}
+
+
+def adapter_for(architecture: Architecture | str) -> ArchitectureBoundaryAdapter:
+    try:
+        return _ADAPTERS[Architecture(architecture)]
+    except (KeyError, ValueError):
+        raise ProtocolError(f"unsupported architecture {architecture!r}") from None

packages/node/meshnet_node/native_protocol/__init__.py

@@ -31,6 +31,8 @@ from .codec import (
     checksum_of,
     crc32c,
     decode_bundle,
+    decode_step_bundle,
+    encode_decode_step,
     decode_tensor,
     default_flow_control,
     encode_bundle,
@@ -40,6 +42,7 @@ from .codec import (
     negotiate_flow_control,
     plan_prefill_chunks,
     validate_session_message_size,
+    validate_tail_result,
 )
 
 __all__ = [
@@ -60,6 +63,8 @@ __all__ = [
     "checksum_of",
     "crc32c",
     "decode_bundle",
+    "decode_step_bundle",
+    "encode_decode_step",
     "decode_tensor",
     "default_flow_control",
     "encode_bundle",
@@ -70,4 +75,5 @@ __all__ = [
     "pb",
     "plan_prefill_chunks",
     "validate_session_message_size",
+    "validate_tail_result",
 ]

packages/node/meshnet_node/native_protocol/codec.py

@@ -328,6 +328,8 @@ def decode_tensor(
 def encode_bundle(
     tensors: Iterable[pb.NamedTensor],
     *,
+    architecture: int = pb.ARCHITECTURE_TYPE_UNSPECIFIED,
+    boundary_point: str = "",
     max_chunk_bytes: int = DEFAULT_MAX_CHUNK_BYTES,
     max_tensors: int = DEFAULT_MAX_TENSORS_PER_BUNDLE,
 ) -> pb.TensorBundle:
@@ -338,7 +340,12 @@ def encode_bundle(
         raise ProtocolError(
             f"bundle carries {len(tensor_list)} tensors, exceeding limit {max_tensors}"
         )
-    bundle = pb.TensorBundle(bundle_version=BUNDLE_VERSION, tensors=tensor_list)
+    bundle = pb.TensorBundle(
+        bundle_version=BUNDLE_VERSION,
+        tensors=tensor_list,
+        architecture=architecture,
+        boundary_point=boundary_point,
+    )
     if bundle.ByteSize() > max_chunk_bytes:
         raise ProtocolError(
             f"serialized tensor bundle exceeds the {max_chunk_bytes}-byte "
@@ -392,6 +399,80 @@ def decode_bundle(
     return payloads
 
 
+def encode_decode_step(
+    bundle: pb.TensorBundle,
+    *,
+    idempotency_step: int,
+    position: int,
+    expected_past_len: int,
+    work_id: str,
+    deadline_unix_nanos: int = 0,
+    prefer_compact_one_tensor: bool = True,
+) -> pb.DecodeStep:
+    """Encode a decode boundary, retaining the deliberate compact fallback."""
+    step = pb.DecodeStep(
+        idempotency_step=idempotency_step,
+        position=position,
+        expected_past_len=expected_past_len,
+        work_id=work_id,
+        deadline_unix_nanos=deadline_unix_nanos,
+    )
+    if prefer_compact_one_tensor and len(bundle.tensors) == 1:
+        step.tensor.CopyFrom(bundle.tensors[0])
+    else:
+        step.bundle.CopyFrom(bundle)
+    return step
+
+
+def validate_tail_result(result: pb.TailResult) -> None:
+    """Fail closed unless a tail completion is bound to its exact recipe."""
+    identity = result.identity
+    required = (
+        identity.request_id,
+        identity.runtime_recipe_digest,
+        identity.chat_template_id,
+        identity.chat_template_version,
+        identity.reasoning_mode,
+    )
+    if not all(required) or identity.architecture == pb.ARCHITECTURE_TYPE_UNSPECIFIED:
+        raise ProtocolError("tail result lacks exact request/recipe/template identity")
+    if result.WhichOneof("output") not in {"logits", "sampled_token_id"}:
+        raise ProtocolError("tail result lacks logits or sampled token output")
+
+
+def decode_step_bundle(
+    step: pb.DecodeStep,
+    *,
+    max_chunk_bytes: int = DEFAULT_MAX_CHUNK_BYTES,
+    max_fragment_bytes: int = DEFAULT_MAX_FRAGMENT_BYTES,
+    max_fragments: int = DEFAULT_MAX_FRAGMENTS_PER_TENSOR,
+    max_tensors: int = DEFAULT_MAX_TENSORS_PER_BUNDLE,
+) -> dict[str, bytes]:
+    """Decode a fast-path boundary with the DGR-006 compatibility rule.
+
+    `bundle` is authoritative because it can carry architecture sidebands. The
+    old `tensor` field remains the compact representation for a certified
+    one-tensor boundary and is accepted by new readers during rollout.
+    """
+    if step.HasField("bundle"):
+        return decode_bundle(
+            step.bundle,
+            max_chunk_bytes=max_chunk_bytes,
+            max_fragment_bytes=max_fragment_bytes,
+            max_fragments=max_fragments,
+            max_tensors=max_tensors,
+        )
+    if step.HasField("tensor"):
+        return decode_bundle(
+            encode_bundle([step.tensor], max_chunk_bytes=max_chunk_bytes),
+            max_chunk_bytes=max_chunk_bytes,
+            max_fragment_bytes=max_fragment_bytes,
+            max_fragments=max_fragments,
+            max_tensors=max_tensors,
+        )
+    raise ProtocolError("decode step carries neither TensorBundle nor legacy tensor")
+
+
 def validate_session_message_size(
     message: pb.SessionRequest | pb.SessionResponse,
     *,

packages/node/meshnet_node/native_protocol/conformance.py

@@ -27,6 +27,7 @@ TESTDATA_DIR = pathlib.Path(__file__).resolve().parents[2] / "native/testdata"
 
 GOLDEN_SESSION_REQUEST = "session_request_golden.binpb"
 GOLDEN_CAPABILITY_REPORT = "capability_report_golden.binpb"
+GOLDEN_DECODE_STEP = "decode_step_golden.binpb"
 
 # Written by the C++ conformance test into its build tree; the Python test picks
 # it up when present to prove the two languages agree byte-for-byte.
@@ -136,6 +137,30 @@ def canonical_capability_report() -> pb.CapabilityReport:
     )
 
 
+def canonical_decode_step() -> pb.SessionRequest:
+    """The DGR-006 multi-tensor decode boundary vector."""
+    hidden = codec.encode_tensor(
+        codec.HIDDEN_STATES, bytes(range(16)), [1, 1, 4], pb.DTYPE_FLOAT32
+    )
+    index_topk = codec.encode_tensor(
+        "index_topk", (3).to_bytes(4, "little"), [1], pb.DTYPE_INT32
+    )
+    return pb.SessionRequest(
+        decode=pb.DecodeStep(
+            idempotency_step=43,
+            position=384,
+            expected_past_len=384,
+            work_id="decode-7f3a",
+            deadline_unix_nanos=DEADLINE_UNIX_NANOS,
+            bundle=codec.encode_bundle(
+                [hidden, index_topk],
+                architecture=pb.ARCHITECTURE_TYPE_MLA,
+                boundary_point="pre_tail_residual",
+            ),
+        )
+    )
+
+
 def serialize(message) -> bytes:
     """Serialize deterministically, so committed golden bytes are stable."""
     return message.SerializeToString(deterministic=True)

packages/node/meshnet_node/native_protocol/generated/shard_runtime_pb2.pyi

@@ -12,6 +12,13 @@ class SchemaVersion(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
     SCHEMA_VERSION_UNSPECIFIED: _ClassVar[SchemaVersion]
     SCHEMA_VERSION_1: _ClassVar[SchemaVersion]
 
+class ArchitectureType(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
+    __slots__ = ()
+    ARCHITECTURE_TYPE_UNSPECIFIED: _ClassVar[ArchitectureType]
+    ARCHITECTURE_TYPE_DENSE: _ClassVar[ArchitectureType]
+    ARCHITECTURE_TYPE_MOE: _ClassVar[ArchitectureType]
+    ARCHITECTURE_TYPE_MLA: _ClassVar[ArchitectureType]
+
 class DType(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
     __slots__ = ()
     DTYPE_UNSPECIFIED: _ClassVar[DType]
@@ -80,6 +87,10 @@ class ServingState(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
     SERVING_STATE_NOT_SERVING: _ClassVar[ServingState]
 SCHEMA_VERSION_UNSPECIFIED: SchemaVersion
 SCHEMA_VERSION_1: SchemaVersion
+ARCHITECTURE_TYPE_UNSPECIFIED: ArchitectureType
+ARCHITECTURE_TYPE_DENSE: ArchitectureType
+ARCHITECTURE_TYPE_MOE: ArchitectureType
+ARCHITECTURE_TYPE_MLA: ArchitectureType
 DTYPE_UNSPECIFIED: DType
 DTYPE_BFLOAT16: DType
 DTYPE_FLOAT16: DType
@@ -165,12 +176,16 @@ class NamedTensor(_message.Message):
     def __init__(self, name: _Optional[str] = ..., shape: _Optional[_Iterable[int]] = ..., dtype: _Optional[_Union[DType, str]] = ..., byte_order: _Optional[_Union[ByteOrder, str]] = ..., total_bytes: _Optional[int] = ..., compression: _Optional[_Union[Compression, str]] = ..., checksum: _Optional[_Union[Checksum, _Mapping]] = ..., fragments: _Optional[_Iterable[_Union[TensorFragment, _Mapping]]] = ...) -> None: ...
 
 class TensorBundle(_message.Message):
-    __slots__ = ("bundle_version", "tensors")
+    __slots__ = ("bundle_version", "tensors", "architecture", "boundary_point")
     BUNDLE_VERSION_FIELD_NUMBER: _ClassVar[int]
     TENSORS_FIELD_NUMBER: _ClassVar[int]
+    ARCHITECTURE_FIELD_NUMBER: _ClassVar[int]
+    BOUNDARY_POINT_FIELD_NUMBER: _ClassVar[int]
     bundle_version: int
     tensors: _containers.RepeatedCompositeFieldContainer[NamedTensor]
-    def __init__(self, bundle_version: _Optional[int] = ..., tensors: _Optional[_Iterable[_Union[NamedTensor, _Mapping]]] = ...) -> None: ...
+    architecture: ArchitectureType
+    boundary_point: str
+    def __init__(self, bundle_version: _Optional[int] = ..., tensors: _Optional[_Iterable[_Union[NamedTensor, _Mapping]]] = ..., architecture: _Optional[_Union[ArchitectureType, str]] = ..., boundary_point: _Optional[str] = ...) -> None: ...
 
 class Fingerprint(_message.Message):
     __slots__ = ("model_artifact_digest", "runtime_recipe_digest", "recipe_id", "recipe_version", "catalogue_version")
@@ -327,20 +342,64 @@ class ActivationChunk(_message.Message):
     def __init__(self, envelope: _Optional[_Union[Envelope, _Mapping]] = ..., bundle: _Optional[_Union[TensorBundle, _Mapping]] = ...) -> None: ...
 
 class DecodeStep(_message.Message):
-    __slots__ = ("idempotency_step", "position", "expected_past_len", "tensor", "work_id", "deadline_unix_nanos")
+    __slots__ = ("idempotency_step", "position", "expected_past_len", "tensor", "work_id", "deadline_unix_nanos", "bundle")
     IDEMPOTENCY_STEP_FIELD_NUMBER: _ClassVar[int]
     POSITION_FIELD_NUMBER: _ClassVar[int]
     EXPECTED_PAST_LEN_FIELD_NUMBER: _ClassVar[int]
     TENSOR_FIELD_NUMBER: _ClassVar[int]
     WORK_ID_FIELD_NUMBER: _ClassVar[int]
     DEADLINE_UNIX_NANOS_FIELD_NUMBER: _ClassVar[int]
+    BUNDLE_FIELD_NUMBER: _ClassVar[int]
     idempotency_step: int
     position: int
     expected_past_len: int
     tensor: NamedTensor
     work_id: str
     deadline_unix_nanos: int
-    def __init__(self, idempotency_step: _Optional[int] = ..., position: _Optional[int] = ..., expected_past_len: _Optional[int] = ..., tensor: _Optional[_Union[NamedTensor, _Mapping]] = ..., work_id: _Optional[str] = ..., deadline_unix_nanos: _Optional[int] = ...) -> None: ...
+    bundle: TensorBundle
+    def __init__(self, idempotency_step: _Optional[int] = ..., position: _Optional[int] = ..., expected_past_len: _Optional[int] = ..., tensor: _Optional[_Union[NamedTensor, _Mapping]] = ..., work_id: _Optional[str] = ..., deadline_unix_nanos: _Optional[int] = ..., bundle: _Optional[_Union[TensorBundle, _Mapping]] = ...) -> None: ...
+
+class RequestRecipeIdentity(_message.Message):
+    __slots__ = ("request_id", "runtime_recipe_digest", "chat_template_id", "chat_template_version", "reasoning_mode", "architecture")
+    REQUEST_ID_FIELD_NUMBER: _ClassVar[int]
+    RUNTIME_RECIPE_DIGEST_FIELD_NUMBER: _ClassVar[int]
+    CHAT_TEMPLATE_ID_FIELD_NUMBER: _ClassVar[int]
+    CHAT_TEMPLATE_VERSION_FIELD_NUMBER: _ClassVar[int]
+    REASONING_MODE_FIELD_NUMBER: _ClassVar[int]
+    ARCHITECTURE_FIELD_NUMBER: _ClassVar[int]
+    request_id: str
+    runtime_recipe_digest: str
+    chat_template_id: str
+    chat_template_version: str
+    reasoning_mode: str
+    architecture: ArchitectureType
+    def __init__(self, request_id: _Optional[str] = ..., runtime_recipe_digest: _Optional[str] = ..., chat_template_id: _Optional[str] = ..., chat_template_version: _Optional[str] = ..., reasoning_mode: _Optional[str] = ..., architecture: _Optional[_Union[ArchitectureType, str]] = ...) -> None: ...
+
+class SamplingParameters(_message.Message):
+    __slots__ = ("temperature", "top_p", "top_k", "seed", "greedy")
+    TEMPERATURE_FIELD_NUMBER: _ClassVar[int]
+    TOP_P_FIELD_NUMBER: _ClassVar[int]
+    TOP_K_FIELD_NUMBER: _ClassVar[int]
+    SEED_FIELD_NUMBER: _ClassVar[int]
+    GREEDY_FIELD_NUMBER: _ClassVar[int]
+    temperature: float
+    top_p: float
+    top_k: int
+    seed: int
+    greedy: bool
+    def __init__(self, temperature: _Optional[float] = ..., top_p: _Optional[float] = ..., top_k: _Optional[int] = ..., seed: _Optional[int] = ..., greedy: _Optional[bool] = ...) -> None: ...
+
+class TailResult(_message.Message):
+    __slots__ = ("identity", "sampling", "logits", "sampled_token_id")
+    IDENTITY_FIELD_NUMBER: _ClassVar[int]
+    SAMPLING_FIELD_NUMBER: _ClassVar[int]
+    LOGITS_FIELD_NUMBER: _ClassVar[int]
+    SAMPLED_TOKEN_ID_FIELD_NUMBER: _ClassVar[int]
+    identity: RequestRecipeIdentity
+    sampling: SamplingParameters
+    logits: TensorBundle
+    sampled_token_id: int
+    def __init__(self, identity: _Optional[_Union[RequestRecipeIdentity, _Mapping]] = ..., sampling: _Optional[_Union[SamplingParameters, _Mapping]] = ..., logits: _Optional[_Union[TensorBundle, _Mapping]] = ..., sampled_token_id: _Optional[int] = ...) -> None: ...
 
 class ReleaseSignal(_message.Message):
     __slots__ = ("route_session_id", "route_epoch", "work_id")
@@ -409,18 +468,20 @@ class SessionRequest(_message.Message):
     def __init__(self, open: _Optional[_Union[SessionOpen, _Mapping]] = ..., chunk: _Optional[_Union[ActivationChunk, _Mapping]] = ..., decode: _Optional[_Union[DecodeStep, _Mapping]] = ..., flow_control: _Optional[_Union[FlowControl, _Mapping]] = ..., release: _Optional[_Union[ReleaseSignal, _Mapping]] = ..., cancel: _Optional[_Union[CancelSignal, _Mapping]] = ...) -> None: ...
 
 class SessionResponse(_message.Message):
-    __slots__ = ("accepted", "chunk", "ack", "flow_control", "status")
+    __slots__ = ("accepted", "chunk", "ack", "flow_control", "status", "tail_result")
     ACCEPTED_FIELD_NUMBER: _ClassVar[int]
     CHUNK_FIELD_NUMBER: _ClassVar[int]
     ACK_FIELD_NUMBER: _ClassVar[int]
     FLOW_CONTROL_FIELD_NUMBER: _ClassVar[int]
     STATUS_FIELD_NUMBER: _ClassVar[int]
+    TAIL_RESULT_FIELD_NUMBER: _ClassVar[int]
     accepted: SessionAccepted
     chunk: ActivationChunk
     ack: Ack
     flow_control: FlowControl
     status: ShardStatus
-    def __init__(self, accepted: _Optional[_Union[SessionAccepted, _Mapping]] = ..., chunk: _Optional[_Union[ActivationChunk, _Mapping]] = ..., ack: _Optional[_Union[Ack, _Mapping]] = ..., flow_control: _Optional[_Union[FlowControl, _Mapping]] = ..., status: _Optional[_Union[ShardStatus, _Mapping]] = ...) -> None: ...
+    tail_result: TailResult
+    def __init__(self, accepted: _Optional[_Union[SessionAccepted, _Mapping]] = ..., chunk: _Optional[_Union[ActivationChunk, _Mapping]] = ..., ack: _Optional[_Union[Ack, _Mapping]] = ..., flow_control: _Optional[_Union[FlowControl, _Mapping]] = ..., status: _Optional[_Union[ShardStatus, _Mapping]] = ..., tail_result: _Optional[_Union[TailResult, _Mapping]] = ...) -> None: ...
 
 class CapabilityRequest(_message.Message):
     __slots__ = ("schema_version",)

packages/node/native/README.md

@@ -32,6 +32,15 @@ Both `--check` modes run in CI via `tests/test_native_shard_protocol.py`, so a
 schema edit that is not accompanied by regenerated output fails the suite rather
 than shipping stubs that disagree with the schema they claim to implement.
 
+## DGR-006 decode and tail compatibility
+
+`DecodeStep.bundle` is the versioned `TensorBundle` fast-path boundary. It is
+authoritative whenever present and supports architecture sidebands. The original
+`DecodeStep.tensor` remains readable as the compact one-tensor encoding for
+certified boundaries that need only one tensor; new readers wrap it into a
+one-member bundle. Tail completions use `TailResult`, which binds logits or a
+sampled token to request/recipe identity and sampling/template/reasoning inputs.
+
 ## Building and running the C++ conformance test
 
 If the machine has no protobuf C++ toolchain:

packages/node/native/proto/shard_runtime.proto

@@ -33,6 +33,16 @@ enum SchemaVersion {
   SCHEMA_VERSION_1 = 1;
 }
 
+// Certified transformer boundary family.  Names alone are not an adapter: a
+// Node must select an explicit architecture contract before interpreting a
+// TensorBundle.
+enum ArchitectureType {
+  ARCHITECTURE_TYPE_UNSPECIFIED = 0;
+  ARCHITECTURE_TYPE_DENSE = 1;
+  ARCHITECTURE_TYPE_MOE = 2;
+  ARCHITECTURE_TYPE_MLA = 3;
+}
+
 // ---------------------------------------------------------------------------
 // Tensor bundle — the public activation boundary
 // ---------------------------------------------------------------------------
@@ -142,6 +152,11 @@ message TensorBundle {
   // boundary payload can evolve without a whole-protocol version bump.
   uint32 bundle_version = 1;
   repeated NamedTensor tensors = 2;
+  // Explicit adapter selection; names are never interpreted through unchecked
+  // substitutions. UNSPECIFIED is accepted only for legacy DGR-002 bundles.
+  ArchitectureType architecture = 3;
+  // Adapter-owned semantic boundary, such as "pre_tail_residual".
+  string boundary_point = 4;
 }
 
 // ---------------------------------------------------------------------------
@@ -393,8 +408,9 @@ message ActivationChunk {
 // A decode step is one token: the envelope's identity fields are already fixed
 // for the life of the stream, so repeating them per token is pure overhead on
 // the hottest path. A DecodeStep carries only what changes — the step, the
-// position, and one tensor — and inherits the rest from the SessionOpen
+// position, and one compact boundary encoding — and inherits the rest from the
-// handshake. A peer may always fall back to ActivationChunk with PHASE_DECODE.
+// SessionOpen handshake.  A Node may always fall back to ActivationChunk with
+// PHASE_DECODE.
 message DecodeStep {
   // Idempotency step within the session; also orders the stream.
   uint64 idempotency_step = 1;
@@ -402,11 +418,50 @@ message DecodeStep {
   uint64 position = 2;
   // Tokens the receiver's cache must already hold. A mismatch is a CACHE_MISS.
   uint64 expected_past_len = 3;
-  // The single boundary tensor for this token, typically [1, 1, hidden].
+  // Legacy compact one-tensor boundary, typically [1, 1, hidden]. New readers
+  // accept it as a TensorBundle with one member; writers retain it where the
+  // selected architecture genuinely requires only one tensor.
   NamedTensor tensor = 4;
   // Work id for attribution; the session/epoch/fingerprint/range are inherited.
   string work_id = 5;
   int64 deadline_unix_nanos = 6;
+  // Versioned architecture boundary. This carries sidebands such as MoE router
+  // state or MLA/IndexShare state; when both fields are set, bundle is
+  // authoritative and tensor is retained only for older-Node forwarding.
+  TensorBundle bundle = 7;
+}
+
+// Exact request-level identity for a tail result. Runtime recipe identity is
+// deliberately repeated here: sampling the right logits with the wrong chat
+// template or reasoning mode is a different request, not a compatible result.
+message RequestRecipeIdentity {
+  string request_id = 1;
+  string runtime_recipe_digest = 2;
+  string chat_template_id = 3;
+  string chat_template_version = 4;
+  string reasoning_mode = 5;
+  ArchitectureType architecture = 6;
+}
+
+// Sampling is an explicit tail-only operation. A non-tail Shard never applies
+// final norm, LM head, row pruning, or sampling to its boundary output.
+message SamplingParameters {
+  float temperature = 1;
+  float top_p = 2;
+  uint32 top_k = 3;
+  uint64 seed = 4;
+  bool greedy = 5;
+}
+
+// Typed tail completion. The oneof keeps token id 0 unambiguous and prevents a
+// caller from treating an activation tensor as an inferred completion.
+message TailResult {
+  RequestRecipeIdentity identity = 1;
+  SamplingParameters sampling = 2;
+  oneof output {
+    TensorBundle logits = 3;
+    uint32 sampled_token_id = 4;
+  }
 }
 
 // Drop session state for a Route Session. Bounded memory does not depend on
@@ -471,7 +526,8 @@ message SessionResponse {
     ActivationChunk chunk = 2;
     Ack ack = 3;
     FlowControl flow_control = 4;
-    ShardStatus status = 5;
+  ShardStatus status = 5;
+  TailResult tail_result = 6;
   }
 }
 

packages/node/native/tests/test_shard_protocol_conformance.cpp

@@ -265,7 +265,9 @@ void TestDecodeFastPathIsSmall() {
   step->set_position(1024);
   step->set_expected_past_len(1024);
   step->set_work_id("work-7f3a");
-  sp::NamedTensor *tensor = step->mutable_tensor();
+  sp::TensorBundle *bundle = step->mutable_bundle();
+  bundle->set_bundle_version(1);
+  sp::NamedTensor *tensor = bundle->add_tensors();
   tensor->set_name("hidden_states");
   tensor->add_shape(1);
   tensor->add_shape(1);
@@ -290,7 +292,27 @@ void TestDecodeFastPathIsSmall() {
   CHECK(parsed.ParseFromString(bytes));
   CHECK(parsed.kind_case() == sp::SessionRequest::kDecode);
   CHECK_EQ(parsed.decode().position(), 1024u);
-  CHECK_EQ(parsed.decode().tensor().total_bytes(), 16u);
+  CHECK_EQ(parsed.decode().bundle().tensors_size(), 1);
+  CHECK_EQ(parsed.decode().bundle().tensors(0).total_bytes(), 16u);
+}
+
+void TestDecodeBundleVector(const std::string &bytes) {
+  sp::SessionRequest request;
+  CHECK(request.ParseFromString(bytes));
+  CHECK(request.kind_case() == sp::SessionRequest::kDecode);
+  const sp::DecodeStep &step = request.decode();
+  CHECK_EQ(step.idempotency_step(), 43u);
+  CHECK_EQ(step.position(), 384u);
+  CHECK_EQ(step.expected_past_len(), 384u);
+  CHECK_EQ(step.work_id(), std::string("decode-7f3a"));
+  CHECK(step.has_bundle());
+  CHECK_EQ(step.bundle().bundle_version(), 1u);
+  CHECK_EQ(step.bundle().architecture(), sp::ARCHITECTURE_TYPE_MLA);
+  CHECK_EQ(step.bundle().boundary_point(), std::string("pre_tail_residual"));
+  CHECK_EQ(step.bundle().tensors_size(), 2);
+  CHECK_EQ(step.bundle().tensors(0).name(), std::string("hidden_states"));
+  CHECK_EQ(step.bundle().tensors(1).name(), std::string("index_topk"));
+  CHECK_EQ(step.bundle().tensors(1).dtype(), sp::DTYPE_INT32);
 }
 
 }  // namespace
@@ -308,9 +330,11 @@ int main(int argc, char **argv) {
       ReadFile(testdata / "session_request_golden.binpb");
   const std::string capability_bytes =
       ReadFile(testdata / "capability_report_golden.binpb");
+  const std::string decode_bytes = ReadFile(testdata / "decode_step_golden.binpb");
 
   TestSessionRequestVector(session_bytes);
   TestCapabilityReportVector(capability_bytes);
+  TestDecodeBundleVector(decode_bytes);
   TestUnknownFieldsArePreserved(session_bytes);
   TestSparseMessageParses();
   TestDecodeFastPathIsSmall();

scripts/generate_protocol_goldens.py

@@ -33,6 +33,9 @@ def _vectors() -> dict[str, bytes]:
         conformance.GOLDEN_CAPABILITY_REPORT: conformance.serialize(
             conformance.canonical_capability_report()
         ),
+        conformance.GOLDEN_DECODE_STEP: conformance.serialize(
+            conformance.canonical_decode_step()
+        ),
     }
 
 

tests/test_architecture_boundary.py

@@ -0,0 +1,121 @@
+"""DGR-006 architecture-defined activation-boundary contract."""
+
+from __future__ import annotations
+
+import struct
+
+import pytest
+
+from meshnet_node.architecture_boundary import (
+    Architecture,
+    BoundaryStage,
+    ProtocolIdentity,
+    SamplingParameters,
+    TailOutput,
+    adapter_for,
+)
+from meshnet_node.native_protocol import ProtocolError, decode_bundle
+
+
+def _f32(values: list[float]) -> bytes:
+    return struct.pack("<" + "f" * len(values), *values)
+
+
+def _values(payload: bytes) -> tuple[float, ...]:
+    return struct.unpack("<" + "f" * (len(payload) // 4), payload)
+
+
+def test_dense_whole_model_and_two_ranges_match_for_prefill_and_greedy_decode() -> None:
+    adapter = adapter_for(Architecture.DENSE)
+    embeddings = {3: [1.0, 2.0], 7: [3.0, 4.0]}
+    head = adapter.bundle_from_token_ids([3, 7], lambda token: embeddings[token])
+
+    def head_layers(bundle):
+        return [value + 10.0 for value in _values(decode_bundle(bundle)["hidden_states"])]
+
+    def tail_layers(residual: list[float]) -> tuple[list[float], int]:
+        # The tail alone applies this fixture's final norm/head and greedy argmax.
+        logits = [sum(residual) / len(residual) + 20.0, 0.0]
+        return logits, max(range(len(logits)), key=logits.__getitem__)
+
+    # Whole-model prefill retains the unnormalized residual locally. The
+    # two-range lane sends that same residual before the tail-only head.
+    whole_prefill = head_layers(head)
+    seam = adapter.bundle_from_named_payloads(
+        {"hidden_states": _f32(whole_prefill)}, shape=[1, 2, 2]
+    )
+    two_range_prefill = list(_values(decode_bundle(adapter.input_for(BoundaryStage.TAIL, seam))["hidden_states"]))
+    assert two_range_prefill == whole_prefill
+
+    whole_logits, whole_token = tail_layers(whole_prefill)
+    two_logits, two_token = tail_layers(two_range_prefill)
+    assert two_logits == whole_logits
+    assert two_token == whole_token == 0
+
+    # One greedy decode step is the same contract with [batch, token, hidden].
+    decode_seam = adapter.bundle_from_named_payloads(
+        {"hidden_states": _f32([5.0, 6.0])}, shape=[1, 1, 2]
+    )
+    assert tail_layers([5.0, 6.0]) == tail_layers(
+        list(_values(decode_bundle(adapter.input_for(BoundaryStage.TAIL, decode_seam))["hidden_states"]))
+    )
+
+
+def test_middle_and_tail_reject_token_ids_and_require_boundary_bundle() -> None:
+    adapter = adapter_for(Architecture.MOE)
+
+    with pytest.raises(ProtocolError, match="head"):
+        adapter.bundle_from_token_ids([1], lambda _: [1.0])
+
+    with pytest.raises(ProtocolError, match="TensorBundle"):
+        adapter.input_for(BoundaryStage.MIDDLE, None)
+
+
+@pytest.mark.parametrize(
+    ("architecture", "names"),
+    [
+        (Architecture.MOE, {"hidden_states", "router_logits"}),
+        (Architecture.MLA, {"hidden_states", "mla_position_state"}),
+    ],
+)
+def test_architecture_adapters_route_and_validate_their_named_sidebands(
+    architecture: Architecture, names: set[str]
+) -> None:
+    adapter = adapter_for(architecture)
+    bundle = adapter.bundle_from_named_payloads(
+        {
+            name: (_f32([1.0, 2.0]) if name == "hidden_states" else _f32([0.0]))
+            for name in names
+        }
+    )
+
+    assert set(decode_bundle(adapter.input_for(BoundaryStage.MIDDLE, bundle))) == names
+    with pytest.raises(ProtocolError, match="requires"):
+        adapter.bundle_from_named_payloads({"hidden_states": _f32([1.0, 2.0])})
+
+
+def test_unknown_architecture_fails_closed() -> None:
+    with pytest.raises(ProtocolError, match="unsupported architecture"):
+        adapter_for("unchecked-name-substitution")
+
+
+def test_typed_tail_result_binds_sampling_and_request_recipe_identity() -> None:
+    adapter = adapter_for(Architecture.DENSE)
+    identity = ProtocolIdentity(
+        request_id="request-1",
+        runtime_recipe_digest="sha256:recipe",
+        chat_template_id="llama3",
+        chat_template_version="2",
+        reasoning_mode="max",
+        architecture=Architecture.DENSE,
+    )
+    result = adapter.tail_result(
+        identity=identity,
+        sampling=SamplingParameters(temperature=0.0, top_p=1.0, top_k=0, seed=9),
+        output=TailOutput.sampled_token(42),
+    )
+
+    assert result.identity.request_id == "request-1"
+    assert result.sampled_token_id == 42
+    assert result.output_kind == "sampled_token_id"
+    assert result.message.WhichOneof("output") == "sampled_token_id"

tests/test_native_shard_protocol.py

@@ -34,6 +34,8 @@ from meshnet_node.native_protocol import (
     ProtocolError,
     checksum_of,
     decode_bundle,
+    decode_step_bundle,
+    encode_decode_step,
     decode_tensor,
     default_flow_control,
     encode_bundle,
@@ -429,7 +431,7 @@ def test_decode_fast_path_is_much_smaller_than_a_full_envelope_chunk():
             idempotency_step=9,
             position=1024,
             expected_past_len=1024,
-            tensor=tensor,
+            bundle=encode_bundle([tensor]),
             work_id="work-7f3a",
         )
     )
@@ -443,7 +445,48 @@ def test_decode_fast_path_is_much_smaller_than_a_full_envelope_chunk():
     )
 
     assert len(fast.SerializeToString()) * 2 < len(full.SerializeToString())
-    assert decode_tensor(fast.decode.tensor) == hidden
+    assert decode_step_bundle(fast.decode) == {HIDDEN_STATES: hidden}
+
+
+def test_decode_fast_path_preserves_legacy_one_tensor_compatibility():
+    tensor = encode_tensor(HIDDEN_STATES, b"\x01\x02" * 8, [1, 1, 8], pb.DTYPE_BFLOAT16)
+    legacy = pb.DecodeStep(tensor=tensor)
+
+    assert decode_step_bundle(legacy) == {HIDDEN_STATES: b"\x01\x02" * 8}
+
+
+def test_decode_bundle_wins_over_legacy_tensor_and_can_carry_sidebands():
+    hidden = encode_tensor(HIDDEN_STATES, b"\x01\x02" * 8, [1, 1, 8], pb.DTYPE_BFLOAT16)
+    sideband = encode_tensor("index_topk", b"\x00" * 4, [1], pb.DTYPE_INT32)
+    decode = pb.DecodeStep(tensor=hidden, bundle=encode_bundle([hidden, sideband]))
+
+    assert decode_step_bundle(decode) == {
+        HIDDEN_STATES: b"\x01\x02" * 8,
+        "index_topk": b"\x00" * 4,
+    }
+
+
+def test_decode_writer_uses_compact_tensor_only_for_a_certified_one_tensor_bundle():
+    hidden = encode_tensor(HIDDEN_STATES, b"\x01\x02" * 8, [1, 1, 8], pb.DTYPE_BFLOAT16)
+    compact = encode_decode_step(
+        encode_bundle([hidden]), idempotency_step=1, position=1, expected_past_len=1, work_id="w"
+    )
+    sideband = encode_tensor("index_topk", b"\x00" * 4, [1], pb.DTYPE_INT32)
+    expanded = encode_decode_step(
+        encode_bundle([hidden, sideband]), idempotency_step=1, position=1, expected_past_len=1, work_id="w"
+    )
+
+    assert compact.HasField("tensor") and not compact.HasField("bundle")
+    assert expanded.HasField("bundle") and not expanded.HasField("tensor")
+
+
+def test_schema_exposes_typed_tail_result_and_bound_sampling_identity():
+    assert {"identity", "sampling", "logits", "sampled_token_id"} <= set(
+        pb.TailResult.DESCRIPTOR.fields_by_name
+    )
+    assert {"request_id", "runtime_recipe_digest", "chat_template_id", "chat_template_version", "reasoning_mode"} <= set(
+        pb.RequestRecipeIdentity.DESCRIPTOR.fields_by_name
+    )
 
 
 def test_flow_control_defaults_bound_the_queue_and_the_message():
@@ -491,6 +534,20 @@ def test_committed_vectors_still_encode_as_promised():
     report = (conformance.TESTDATA_DIR / conformance.GOLDEN_CAPABILITY_REPORT).read_bytes()
     assert conformance.serialize(conformance.canonical_capability_report()) == report
 
+    decode = (conformance.TESTDATA_DIR / conformance.GOLDEN_DECODE_STEP).read_bytes()
+    assert conformance.serialize(conformance.canonical_decode_step()) == decode
+
+
+def test_decode_golden_preserves_the_multi_tensor_boundary():
+    golden = (conformance.TESTDATA_DIR / conformance.GOLDEN_DECODE_STEP).read_bytes()
+    request = pb.SessionRequest.FromString(golden)
+
+    assert request.decode.idempotency_step == 43
+    assert decode_step_bundle(request.decode) == {
+        HIDDEN_STATES: bytes(range(16)),
+        "index_topk": (3).to_bytes(4, "little"),
+    }
+
 
 def test_golden_session_request_round_trips_with_every_field_intact():
     golden = (conformance.TESTDATA_DIR / conformance.GOLDEN_SESSION_REQUEST).read_bytes()