Bridge causal data sources into shared SL

agent_context/MAP.yaml

@@ -548,7 +548,7 @@ topics:
 - id: supervised-learning
   title: Supervised Learning
   aliases: [supervised learning, SL learning, 监督学习, 统一监督学习]
-  keywords: [train-sl, SupervisedBatch, LossResult, SupervisedObjective, SupervisedLearner, SupervisedTrainer, TensorBatchSource, distributed_run, torchrun, DDP, 单机多卡, 分布式监督学习]
+  keywords: [train-sl, SupervisedBatch, LossResult, SupervisedObjective, SupervisedLearner, SupervisedTrainer, TensorBatchSource, SequenceBatchSource, distributed_run, torchrun, DDP, 单机多卡, 分布式监督学习]
   paths: [topics/supervised-learning/supervised-learning.md]
   source_of_truth:
   - embodichain/learning/sl/

agent_context/topics/data-pipeline/data-pipeline.md

@@ -49,6 +49,11 @@ requires explicit action semantics, step duration, field mapping and a resident
 memory limit; imports do not initialize simulation or import the SDK until load.
 The first backend samples resident numeric tensors after bounded SDK reads.
 
+`learning/sl/sequence.py` bridges these sources through an explicit encoder;
+the [SL context](../supervised-learning/supervised-learning.md) owns its identity
+and recovery admission. Online lifecycle and delivery credits remain here.
+Neither trainer RNG restoration nor encoding failure rewinds source quotas.
+
 The demo's `lerobot.py` owns writing and sidecar/hash auditing around the public
 reader. It measures initial loading rather than per-batch disk reads and does
 not replace recording or offline-inspection tools. See the

agent_context/topics/supervised-learning/supervised-learning.md

@@ -14,6 +14,12 @@ operations remain in `compute`; source storage belongs to data adapters.
   update. Its optional numerical context covers forward, backward and clipping.
 - `TensorBatchSource` snapshots fixed CPU tensor trees and returns owned samples
   under the caller's explicit CPU generator.
+- Optional `SequenceBatchSource` in `learning/sl/sequence.py` adapts a data-pipeline
+  `BatchSource` using an explicit versioned encoder. It preserves canonical masks
+  and provenance under reserved `metadata['sequence_source']`, excluding raw
+  observations/actions there. Encoders select causal inputs and supervision;
+  model families retain action/codec/objective semantics. Core SL imports do not
+  load this bridge, ODS or the SDK. See `examples/learning/sl_data_source/`.
 - `SupervisedTrainer` in `learning/sl/trainer.py` composes a source and learner,
   saving optimizer, RNG, sampling progress, source identity and recipe semantics.
 - `embodichain train-sl --config FILE [--resume FILE]` lazily resolves a
@@ -41,6 +47,16 @@ replacement, so samples may overlap. All ranks call fitting, saving and recovery
 only rank 0 writes artifacts or runs validation through the unwrapped model.
 Schema, action/frame/timestep and numerical-policy identifiers belong in each
 recipe's checkpoint signature. Tensor sources additionally bind content identity.
+The sequence bridge defaults to refusing exact resume. Explicitly immutable,
+unbudgeted resident sources bind actual CPU content, schema, window, encoder
+version and semantic metadata (including language); storage diagnostics do not.
+Sampling checks declarations, quota and tensor versions; resume rehashes content
+in bounded blocks. An optional source `validate_resume()` preflight runs inside
+the collective checkpoint validation before any trainer state or output admission
+changes. Live buffers and delivery credits are not restored: such sources may
+train/save snapshots, but exact continuation is rejected. Acquisition, waits,
+refill and delivery debits stay source/caller-owned; encoding failures do not
+refund a delivered context.
 Distributed checkpoints retain each rank's RNG, sampler and buffers and require
 the same world size for exact recovery. Inside rank 0's validation callback only,
 a save uses the previously gathered committed-update snapshot without a new
@@ -62,4 +78,5 @@ nonfinite update boundaries, owned samples, simulator-free imports and exact
 CPU recovery with dropout, optimizer and sampling state. Model-specific
 qualification belongs to each model's acceptance recipe. The distributed tests
 exercise weighted global updates and fixed-world-size recovery with CPU/Gloo;
-the example is validated by launch smoke runs rather than example-specific tests.
+sequence tests reuse real CPU source fixtures for masks, provenance, owned output,
+quota and recovery admission. Examples use launch smoke checks, not tutorial tests.

docs/source/api_reference/embodichain/embodichain.learning.sl.rst

@@ -102,6 +102,7 @@ embodichain.learning.sl
    SupervisedLearner
    SupervisedSource
    TensorBatchSource
+   SequenceBatchSource
    SupervisedTrainer
    SupervisedTrainerCfg
    distributed_run
@@ -124,6 +125,9 @@ embodichain.learning.sl
 .. autoclass:: TensorBatchSource
    :members:
 
+.. autoclass:: SequenceBatchSource
+   :members:
+
 .. autoclass:: SupervisedTrainer
    :members:
 
@@ -155,6 +159,39 @@ embodichain.learning.sl.learner
 .. autoclass:: SupervisedLearner
    :members:
 
+embodichain.learning.sl.sequence
+--------------------------------
+
+.. currentmodule:: embodichain.learning.sl.sequence
+
+.. autosummary::
+
+   SequenceBatchSource
+
+.. autoclass:: SequenceBatchSource
+   :members:
+
+The optional bridge samples one canonical causal window and calls an explicit,
+versioned encoder. It preserves original masks and provenance under the reserved
+``metadata['sequence_source']`` namespace, excluding observations and actions
+from that diagnostic context. The encoder deliberately selects measured inputs
+and supervision; the adapter infers neither action meaning nor feature layout.
+The runnable ``examples/learning/sl_data_source`` example demonstrates action
+targets and causal state-transition targets using a tiny synthetic CPU corpus.
+
+Exact recovery is disabled by default. ``immutable=True`` requires an unchanged,
+content-hashed resident ``TensorDataSource`` (including ``LeRobotDataSource``)
+without sampling quotas. Schema, window, encoder version, language and semantic
+metadata enter identity; storage paths and read/cache diagnostics do not.
+Construction and resume hash CPU content using bounded blocks. Sampling checks
+the immutable promise without rehashing the corpus at every update.
+
+Live or quota-managed sources can train and save snapshots, but exact
+``SupervisedTrainer.resume()`` is rejected collectively before learning, RNG or
+output admission state changes. Producer state and delivery credits are not
+restored by the trainer. Start/stop, refill, waits and handling sampling failures
+remain caller-owned; the bridge performs no retry or quota refund.
+
 embodichain.learning.sl.sources
 -------------------------------
 

embodichain/learning/sl/__init__.py

@@ -18,12 +18,18 @@
 
 from __future__ import annotations
 
+from importlib import import_module
+from typing import TYPE_CHECKING, Any
+
 from .types import LossResult, SupervisedBatch, SupervisedObjective
 from .distributed import distributed_run
 from .learner import SupervisedLearner
 from .sources import SupervisedSource, TensorBatchSource
 from .trainer import SupervisedTrainer, SupervisedTrainerCfg
 
+if TYPE_CHECKING:
+    from .sequence import SequenceBatchSource
+
 __all__ = [
     "LossResult",
     "SupervisedBatch",
@@ -34,4 +40,17 @@
     "SupervisedTrainer",
     "SupervisedTrainerCfg",
     "distributed_run",
+    "SequenceBatchSource",
 ]
+
+
+def __getattr__(name: str) -> Any:
+    if name != "SequenceBatchSource":
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    value = getattr(import_module(f"{__name__}.sequence"), name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | set(__all__))