Skip to content

Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.

fix(compose): convert Time in the PipeCompose whole-stuff matrix (#1101)

Louis Choquel889413d1485c
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5207a8fee..38fd3dad9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -15,6 +15,7 @@
### Fixed
- **Pipe-lookup CLI failures no longer claim "not found" for every failure**: `pipelex codegen inputs` and the `build runner`/`build inputs`/`build output` commands printed a "not found"/"Could not find" prefix on any lookup failure, including an ambiguous bare code — contradicting the ambiguity message printed underneath. The prefix is now verdict-neutral and the underlying error states whether the code was missing or ambiguous.
+- **`Time` now converts in the `PipeCompose` whole-stuff matrix**: A whole `Time` stuff copied into a `time`-typed construct field (`start = { from = "start_time" }`) handed over the `TimeContent` wrapper instead of the time. `Time` was introduced after the conversion matrix was written and was simply never added to it — no rationale ever excluded it. `TimeContent → time` now joins `Text → str`, `Number → float|int`, `YesNo → bool` and `Date → date`, and the plural `Time[] → list[time]` form is covered too. Unlike `Date`, the conversion needs no fidelity guard: a `Time` holds a single value carrying its UTC offset inside its own `tzinfo`, so the copy is lossless. A whole `Date` still does not convert into a bare `time` field, since that would drop the date — the dotted path `{ from = "deadline.time" }` is the route to that value.
## [v0.43.1] - 2026-08-12
diff --git a/docs/building-methods/pipes/pipe-operators/PipeCompose.md b/docs/building-methods/pipes/pipe-operators/PipeCompose.md
index d00d2f48b..04fc9894a 100644
--- a/docs/building-methods/pipes/pipe-operators/PipeCompose.md
+++ b/docs/building-methods/pipes/pipe-operators/PipeCompose.md
@@ -158,7 +158,7 @@ The referenced value must be a list, and every item must carry the key attribute
### Copying Whole Inputs Into Native Fields
-The `from` reference is not limited to dotted paths like `"customer.name"` — it can name a whole input variable. When the referenced input is a native stuff (`Text`, `Number`, `YesNo`, `Date`, or a list of them) and the target field is native-typed, the composer automatically converts the content wrapper into the field's native value. This works for required and optional fields alike.
+The `from` reference is not limited to dotted paths like `"customer.name"` — it can name a whole input variable. When the referenced input is a native stuff (`Text`, `Number`, `YesNo`, `Date`, `Time`, or a list of them) and the target field is native-typed, the composer automatically converts the content wrapper into the field's native value. This works for required and optional fields alike.
Conversion matrix:
@@ -168,15 +168,19 @@ Conversion matrix:
| `Number` | `type = "number"` | the number |
| `YesNo` | `type = "boolean"` | the boolean |
| `Date` | `type = "date"` | the date |
+| `Time` | `type = "time"` | the time of day |
| `Text[]` | `type = "list"`, `item_type = "text"` | the list of strings |
| `Number[]` | `type = "list"`, `item_type = "number"` | the list of numbers |
| `YesNo[]` | `type = "list"`, `item_type = "boolean"` | the list of booleans |
| `Date[]` | `type = "list"`, `item_type = "date"` | the list of dates |
+| `Time[]` | `type = "list"`, `item_type = "time"` | the list of times of day |
When the target field expects a content object rather than a native value (e.g. a field typed with a concept), the object is kept as-is — the conversion only fires when the field expects the native type.
One fidelity guard: a `Date` stuff that carries a time of day cannot be copied into a bare `date` field — that would silently drop the time and its UTC offset, so the composer raises an error instead. Target a `Date`-typed field to keep the full timestamp. The same guard applies per item when copying a `Date[]` into a list of `date` items.
+`Time` needs no such guard, and the asymmetry is deliberate: a `Time` is a single value that carries its UTC offset inside the time itself, so copying it into a `time` field is lossless and nothing can be dropped. In the other direction, a whole `Date` does not convert into a `time` field at all — that would drop the date. Use a dotted path instead, `{ from = "deadline.time" }`, to take the time of day out of a `Date`.
+
Worked example — assembling a report from whole stuffs produced by earlier steps:
```toml
diff --git a/pipelex/pipe_operators/compose/structured_content_composer.py b/pipelex/pipe_operators/compose/structured_content_composer.py
index f065bc47d..531bc30d7 100644
--- a/pipelex/pipe_operators/compose/structured_content_composer.py
+++ b/pipelex/pipe_operators/compose/structured_content_composer.py
@@ -12,6 +12,7 @@ from pipelex.core.stuffs.list_content import ListContent
from pipelex.core.stuffs.number_content import NumberContent
from pipelex.core.stuffs.stuff_content import StuffContent
from pipelex.core.stuffs.text_content import TextContent
+from pipelex.core.stuffs.time_content import TimeContent
from pipelex.core.stuffs.yes_no_content import YesNoContent
from pipelex.kernel.compose_ops import build_compose_context
from pipelex.pipe_operators.compose.construct_blueprint import ConstructBlueprint, ConstructFieldBlueprint, ConstructFieldMethod
@@ -25,12 +26,12 @@ from pipelex.tools.typing.annotation_utils import unwrap_optional
from pipelex.tools.typing.class_utils import are_classes_equivalent
from pipelex.tools.typing.pydantic_utils import format_pydantic_validation_error
-NativeScalarValue: TypeAlias = str | float | int | bool | datetime.date
+NativeScalarValue: TypeAlias = str | float | int | bool | datetime.date | datetime.time
"""The native Python scalar types a content wrapper can be unwrapped into."""
# The exact native scalar target types (no subclass matching: datetime is a date subclass
# and bool is an int subclass, and neither cross-kind conversion is wanted).
-NATIVE_SCALAR_TARGET_TYPES: tuple[type[Any], ...] = (str, float, int, bool, datetime.date)
+NATIVE_SCALAR_TARGET_TYPES: tuple[type[Any], ...] = (str, float, int, bool, datetime.date, datetime.time)
class NativeScalarExtraction(NamedTuple):
@@ -170,6 +171,7 @@ class StructuredContentComposer:
- NumberContent -> float/int: extract .number
- YesNoContent -> bool: extract .yes_no
- DateContent -> date: extract .date
+ - TimeContent -> time: extract .time
- any wrapper -> its own wrapper class/subclass: keep object
- ListContent -> list[native scalar]: extract the scalar from each item
- ListContent -> list[X]: extract items as dicts
@@ -327,8 +329,8 @@ class StructuredContentComposer:
Central dispatcher for type-aware conversion. Native scalar wrappers are unwrapped
first (TextContent -> str, NumberContent -> float/int, YesNoContent -> bool,
- DateContent -> date) when the target expects the native type; otherwise routes to
- specific conversion methods based on content type.
+ DateContent -> date, TimeContent -> time) when the target expects the native type;
+ otherwise routes to specific conversion methods based on content type.
Args:
stuff_content: The content to convert
@@ -388,6 +390,12 @@ class StructuredContentComposer:
- DateContent -> date (exactly, never datetime, a date subclass): extract .date,
but only when the Date carries no time of day — truncating a timestamped Date
to a bare date would silently drop the time and its UTC offset, so it raises
+ - TimeContent -> time (exactly): extract .time, with no fidelity guard — unlike the
+ Date bullet above, the copy is lossless: a TimeContent holds exactly one field and
+ its UTC offset rides inside the time's own tzinfo, so there is nothing to drop
+
+ A whole Date deliberately does not convert into a bare `time` field: that would drop
+ the date. The authored route to that value is the dotted path, e.g. `from = "deadline.time"`.
A wrapper-typed target (e.g. a NumberContent field) deliberately does not match here:
it is handled by the generic StuffContent conversion path so the object is kept.
@@ -423,6 +431,9 @@ class StructuredContentComposer:
)
raise StructuredContentComposerTypeError(msg)
return NativeScalarExtraction(matched=True, value=stuff_content.date)
+ elif isinstance(stuff_content, TimeContent):
+ if expected_type is datetime.time:
+ return NativeScalarExtraction(matched=True, value=stuff_content.time)
return NativeScalarExtraction(matched=False, value=None)
def _convert_list_content(
@@ -619,7 +630,7 @@ class StructuredContentComposer:
def _convert_list_items_as_scalars(self, *, items: list[StuffContent], expected_item_type: type[Any]) -> list[NativeScalarValue]:
"""Extract native scalar values from list item wrappers.
- Used when target is list[X] with X a native scalar type (str/float/int/bool/date):
+ Used when target is list[X] with X a native scalar type (str/float/int/bool/date/time):
each item wrapper is unwrapped to its scalar value (e.g. TextContent -> str).
Args:
diff --git a/tests/integration/pipelex/pipes/operator/pipe_compose_structured/compose_structured_models.mthds b/tests/integration/pipelex/pipes/operator/pipe_compose_structured/compose_structured_models.mthds
index 51585956b..c4d3129ef 100644
--- a/tests/integration/pipelex/pipes/operator/pipe_compose_structured/compose_structured_models.mthds
+++ b/tests/integration/pipelex/pipes/operator/pipe_compose_structured/compose_structured_models.mthds
@@ -60,3 +60,5 @@ NullableTagsHolder = "Holder with a list of nullable str items"
ScoreHolder = "Holder with a float field"
ApprovalHolder = "Holder with a bool field"
DeadlineHolder = "Holder with a date field"
+StartTimeHolder = "Holder with a time field"
+SlotTimesHolder = "Holder with a required list of time field"
diff --git a/tests/integration/pipelex/pipes/operator/pipe_compose_structured/models_for_pipe_compose.py b/tests/integration/pipelex/pipes/operator/pipe_compose_structured/models_for_pipe_compose.py
index a2bcff43f..7ea57c276 100644
--- a/tests/integration/pipelex/pipes/operator/pipe_compose_structured/models_for_pipe_compose.py
+++ b/tests/integration/pipelex/pipes/operator/pipe_compose_structured/models_for_pipe_compose.py
@@ -1,6 +1,6 @@
"""Test StructuredContent models for PipeCompose construct testing."""
-from datetime import date
+from datetime import date, time
from pydantic import Field
@@ -337,7 +337,8 @@ class DocumentBundle(StructuredContent):
# Models for native scalar conversion testing
# These test whole-stuff copies into native-typed fields: the content wrapper
# must be unwrapped to the native value (TextContent -> str, NumberContent -> float,
-# YesNoContent -> bool, DateContent -> date), including into Optional fields.
+# YesNoContent -> bool, DateContent -> date, TimeContent -> time), including into
+# Optional fields.
# ============================================================================
@@ -381,3 +382,15 @@ class DeadlineHolder(StructuredContent):
"""Holder with a date field - should receive DateContent.date extracted."""
deadline: date = Field(description="The deadline date")
+
+
+class StartTimeHolder(StructuredContent):
+ """Holder with a time field - should receive TimeContent.time extracted, UTC offset included."""
+
+ start: time = Field(description="The start time of day")
+
+
+class SlotTimesHolder(StructuredContent):
+ """Holder with a required list[time] field - should receive item times extracted."""
+
+ slots: list[time] = Field(description="The slot times")
diff --git a/tests/integration/pipelex/pipes/operator/pipe_compose_structured/test_data.py b/tests/integration/pipelex/pipes/operator/pipe_compose_structured/test_data.py
index e3100477d..34c268ce1 100644
--- a/tests/integration/pipelex/pipes/operator/pipe_compose_structured/test_data.py
+++ b/tests/integration/pipelex/pipes/operator/pipe_compose_structured/test_data.py
@@ -97,6 +97,16 @@ class NativeScalarConversionTestData:
"deadline": {"from": "deadline_date"},
}
+ # Test case: TimeContent to time field
+ TIME_TO_TIME_CONSTRUCT: ClassVar[dict[str, Any]] = {
+ "start": {"from": "start_time"},
+ }
+
+ # Test case: ListContent[TimeContent] to list[time] field
+ TIME_LIST_TO_TIME_LIST_CONSTRUCT: ClassVar[dict[str, Any]] = {
+ "slots": {"from": "slot_times"},
+ }
+
class ClassCompatibilityTestData:
"""Test data for class compatibility tests."""
diff --git a/tests/integration/pipelex/pipes/operator/pipe_compose_structured/test_pipe_compose_native_scalar_conversions.py b/tests/integration/pipelex/pipes/operator/pipe_compose_structured/test_pipe_compose_native_scalar_conversions.py
index 16a4153fe..a28f9908a 100644
--- a/tests/integration/pipelex/pipes/operator/pipe_compose_structured/test_pipe_compose_native_scalar_conversions.py
+++ b/tests/integration/pipelex/pipes/operator/pipe_compose_structured/test_pipe_compose_native_scalar_conversions.py
@@ -7,6 +7,8 @@ content wrappers into native-typed target fields:
- NumberContent to float field
- YesNoContent to bool field (including a falsy value)
- DateContent to date field
+- TimeContent to time field (UTC offset preserved: the copy is lossless, unlike Date's)
+- ListContent[TimeContent] to list[time] field (item scalar extraction)
"""
import datetime
@@ -24,6 +26,7 @@ from pipelex.core.stuffs.number_content import NumberContent
from pipelex.core.stuffs.stuff_content import StuffContent
from pipelex.core.stuffs.stuff_factory import StuffFactory
from pipelex.core.stuffs.text_content import TextContent
+from pipelex.core.stuffs.time_content import TimeContent
from pipelex.core.stuffs.yes_no_content import YesNoContent
from pipelex.interpreter_hub import get_native_concept, get_pipe_router
from pipelex.pipe_machinery.pipe_factory import PipeFactory
@@ -41,6 +44,21 @@ def _make_tag_texts() -> ListContent[TextContent]:
return ListContent[TextContent](items=[TextContent(text="alpha"), TextContent(text="bravo"), TextContent(text="charlie")])
+# A UTC offset on the middle item: a Time carries its offset inside its own tzinfo, so the
+# list extraction must hand it over untouched, exactly like the singular case.
+_PARIS_OFFSET = datetime.timezone(datetime.timedelta(hours=2))
+
+
+def _make_slot_times() -> ListContent[TimeContent]:
+ return ListContent[TimeContent](
+ items=[
+ TimeContent(time=datetime.time(9, 0)),
+ TimeContent(time=datetime.time(13, 30, tzinfo=_PARIS_OFFSET)),
+ TimeContent(time=datetime.time(17, 15)),
+ ]
+ )
+
+
@pytest.mark.dry_runnable
@pytest.mark.asyncio(loop_scope="class")
class TestPipeComposeNativeScalarConversions:
@@ -131,6 +149,28 @@ class TestPipeComposeNativeScalarConversions:
datetime.date(2026, 3, 14),
id="date_content_to_date_field",
),
+ pytest.param(
+ "compose_time_to_time",
+ "start_time",
+ NativeConceptCode.TIME,
+ TimeContent(time=datetime.time(15, 40, tzinfo=_PARIS_OFFSET)),
+ NativeScalarConversionTestData.TIME_TO_TIME_CONSTRUCT,
+ "StartTimeHolder",
+ "start",
+ datetime.time(15, 40, tzinfo=_PARIS_OFFSET),
+ id="time_content_to_time_field",
+ ),
+ pytest.param(
+ "compose_time_list_to_time_list",
+ "slot_times",
+ NativeConceptCode.TIME,
+ _make_slot_times(),
+ NativeScalarConversionTestData.TIME_LIST_TO_TIME_LIST_CONSTRUCT,
+ "SlotTimesHolder",
+ "slots",
+ [datetime.time(9, 0), datetime.time(13, 30, tzinfo=_PARIS_OFFSET), datetime.time(17, 15)],
+ id="time_list_to_required_time_list_field",
+ ),
],
)
async def test_compose_native_scalar_conversion(
diff --git a/wip/native-date-time/README.md b/wip/native-date-time/README.md
index ba1240d95..968256c06 100644
--- a/wip/native-date-time/README.md
+++ b/wip/native-date-time/README.md
@@ -10,9 +10,11 @@ Tracks the work behind [PR #1089](https://github.com/Pipelex/pipelex/pull/1089)
| `bug-report.md` | The original report, filed from `mthds-ui` while adding native-concept fixture coverage. |
| `plan-and-review-log.md` | The working plan (was `TODOS.md` at the repo root) plus the decision record: every accept and decline across six bot rounds and the final independent review, with the reasoning. |
| `doc-sweep-deferred.md` | The cross-repo doc item deliberately left out of the PR, release-gated. (A second item from the same review concerns another repo and is tracked at workspace level.) |
+| `compose-time-matrix-plan.md` | The follow-up branch `fix/Time-native` (also once the root `TODOS.md`): `Time` was the one native missing from `PipeCompose`'s whole-stuff conversion matrix. Phases 1–3 shipped in this worktree; Phase 4 is an open `mthds-plugins/` doc edit. |
## Still open
- `mthds-ui` (`feature/Native-concepts_stories`): `make fixtures-live ONLY=pipeline_32` replaces the placeholder LIVE fixture with real data — the end-to-end regression check. Gated on a released pipelex carrying the fix.
- Optional pre-release sanity check: run a gateway `PipeLLM` with `output = "Time"` / `Date[]` against the production path.
- The item in `doc-sweep-deferred.md`.
+- Phase 4 of `compose-time-matrix-plan.md`: the `mthds-plugins/` reference template still lists the convertible natives without `Time`.
diff --git a/wip/native-date-time/compose-time-matrix-plan.md b/wip/native-date-time/compose-time-matrix-plan.md
new file mode 100644
index 000000000..0235ae848
--- /dev/null
+++ b/wip/native-date-time/compose-time-matrix-plan.md
@@ -0,0 +1,106 @@
+# `Time` in the PipeCompose whole-stuff conversion matrix
+
+**Goal: close the one native that does not convert.** `PipeCompose`'s construct block unwraps a whole native stuff copied into a plain-typed field — `Text → str`, `Number → float|int`, `YesNo → bool`, `Date → date`. `Time` has no arm, so `start = { from = "start_time" }` into a `time`-typed field hands over the `TimeContent` wrapper instead of the time. This branch adds the arm, its plural counterpart, the tests, and every doc that enumerates the matrix.
+
+**Branch:** `fix/Time-native`, forked from `dev`. **Worktree:** `_time/` — treat it as the pipelex repo root; every path below is relative to it, not to this file's own directory (it was the root `TODOS.md` while the work was in flight).
+
+**Read first:** `wip/native-concepts/time-native-open-questions.md` — in the workspace repo, not this one, so the path does not resolve from here. It carries the decision and the design rationale — *why* each edit, and the three non-obvious points this plan only restates. If you are cold-starting, read its "Design of the accepted solution" section before touching code; it is the difference between making this change and making it correctly.
+
+## Standing constraints
+
+- **No version bump, no new changelog heading.** A version number is a receipt for a published artifact. This work accumulates under the existing `## [Unreleased]` in `CHANGELOG.md`.
+- **Do not push and do not open a PR without asking.** Same for the `mthds-plugins` half.
+- **Phase 4 is not in this worktree.** It is a `mthds-plugins/` change in the workspace checkout. Doing it here is impossible; forgetting it ships a runtime whose own skills documentation contradicts it.
+- **No backward-compat shim.** The matrix simply gains a row.
+
+## The design in one paragraph
+
+Four edits in `pipelex/pipe_operators/compose/structured_content_composer.py`: widen the `NativeScalarValue` alias, add `datetime.time` to `NATIVE_SCALAR_TARGET_TYPES`, add the `TimeContent` arm to `_extract_native_scalar`, and refresh the matrix in the four docstrings that enumerate it. **The tuple entry is the half that is easy to miss** — it is consulted at `_convert_list_content` (routes `list[time]` to the scalar extractor) and at `_validate_item_compatibility` (turns a wrong item type into a loud error rather than a cryptic pydantic one), and it is the entire reason the `Time[]` case needs its own test. The arm needs **no fidelity guard**, unlike `Date`'s: `TimeContent` holds exactly one required field and its UTC offset lives inside the `time`'s own `tzinfo`, so the copy is lossless.
+
+---
+
+## Phase 1 — the runtime arm
+
+- [x] **1.1 — `NativeScalarValue` (`:28`).** Add `datetime.time` to the `TypeAlias`. It types `NativeScalarExtraction.value` and every list-of-scalars return; the new arm does not typecheck without it.
+- [x] **1.2 — `NATIVE_SCALAR_TARGET_TYPES` (`:33`).** Add `datetime.time`. Leave the comment above it as-is — it explains why there is no subclass matching (`datetime` under `date`, `bool` under `int`), which is still exactly right; `time` has no such trap and needs no new prose there.
+- [x] **1.3 — the arm in `_extract_native_scalar`,** as a new `elif` immediately after the `DateContent` branch (`:417`–`:425`), plus `from pipelex.core.stuffs.time_content import TimeContent` at the top:
+
+ ```python
+ elif isinstance(stuff_content, TimeContent):
+ if expected_type is datetime.time:
+ return NativeScalarExtraction(matched=True, value=stuff_content.time)
+ ```
+
+ ⚠ **Identity check, not `_expects_type`.** Matches the `DateContent` arm and, more importantly, matches the plural path — which decides membership with `in` against the tuple, i.e. by identity. Using `_expects_type` here would let a `time` subclass convert as a scalar field and then fail as a list item.
+ ⚠ **Do not add a fidelity guard.** There is nothing to drop. If you find yourself writing one, re-read the design doc — the `Date` guard exists because `DateContent` has two fields, not because temporal copies are inherently lossy.
+ ⚠ **Do not add a `DateContent → datetime.time` arm.** A whole `Date` into a bare `time` field drops the date; the authored route is the dotted path `from = "the_date.time"`, which already works.
+- [x] **1.4 — the four docstring enumerations.** All in the same file; the last one is a bare parenthetical and is the one that gets forgotten:
+ - `_resolve_from_var` (`:169`–`:176`) — the bulleted conversion list.
+ - `_convert_for_target_type` (`:329`) — the inline sentence.
+ - `_extract_native_scalar` (`:384`–`:390`) — the "Conversion matrix" block. Say explicitly that `TimeContent → time` is lossless and needs no guard, so the asymmetry with the `Date` bullet directly above it reads as deliberate.
+ - `_convert_list_items_as_scalars` (`:622`) — the type list *"(str/float/int/bool/date)"*.
+
+## Phase 2 — tests
+
+Both cases go in `tests/integration/pipelex/pipes/operator/pipe_compose_structured/`, in the existing `test_compose_native_scalar_conversion` parametrize list. The class is `@pytest.mark.dry_runnable` — no inference, no marker changes.
+
+- [x] **2.1 — singular: `TimeContent → time`.** Mirror `date_content_to_date_field` exactly:
+ - `compose_structured_models.mthds` — a concept line beside `DeadlineHolder` in the "Native scalar conversion testing concepts" block, e.g. `StartTimeHolder = "Holder with a time field"`. Keep the column alignment of that block.
+ - `models_for_pipe_compose.py` — a `StartTimeHolder(StructuredContent)` beside `DeadlineHolder`, with `start: time = Field(...)`. The module imports `from datetime import date` today — widen it to `date, time`.
+ - `test_data.py` — a `TIME_TO_TIME_CONSTRUCT` beside `DATE_TO_DATE_CONSTRUCT`.
+ - the test module — a `pytest.param` with `NativeConceptCode.TIME`, `TimeContent(time=...)`, and `id="time_content_to_time_field"`. **Use a time that carries a UTC offset** (`datetime.time(15, 40, tzinfo=datetime.timezone(datetime.timedelta(hours=2)))`) and assert it survives — that is the claim that the arm is lossless where `Date`'s is guarded, and a naive-time fixture would not test it.
+- [x] **2.2 — plural: `ListContent[TimeContent] → list[time]`.** This is what covers the `NATIVE_SCALAR_TARGET_TYPES` entry from 1.2; without it that line is untested and a future edit can drop it silently. Same four files, following the `text_list_to_required_str_list_field` shape (a module-level `_make_...` helper builds the `ListContent`, and `input_concept_code` stays the singular `NativeConceptCode.TIME`).
+- [x] **2.3 — update the test module's header docstring** (`:3`–`:10`), which enumerates what the module covers and currently stops at *"DateContent to date field"*.
+- [x] **2.4 — run the targeted suite.** Source areas touched: `pipe_operators/` plus a `.mthds` fixture, so per `tests/CLAUDE.md` that is the pipe tests plus the builder ones:
+
+ ```bash
+ .venv/bin/pytest -n auto \
+ -m "(dry_runnable or not (inference or llm or img_gen or extract or search)) and not pipelex_api" \
+ -o log_level=WARNING --tb=short -q \
+ tests/unit/pipelex/pipe_operators/ tests/integration/pipelex/pipes/ \
+ tests/unit/pipelex/builder/ tests/integration/pipelex/builder/
+ ```
+
+- [x] **2.5 — confirm the new cases actually fail without the fix.** Stash Phase 1, run 2.1 and 2.2, see them fail; restore. A conversion test that passes against the unfixed runtime is testing nothing — and the two fail differently, which is worth seeing once: the singular quietly hands the `TimeContent` wrapper to the field, while the plural falls all the way through `_validate_item_compatibility`'s four cases (none of which match, precisely because the tuple entry is missing) and dumps the items as dicts, failing later in pydantic validation of `list[time]`. That second trace is the argument for 1.2 in concrete form.
+
+## Phase 3 — docs and changelog
+
+- [x] **3.1 — `docs/building-methods/pipes/pipe-operators/PipeCompose.md`,** section "Copying Whole Inputs Into Native Fields". Three separate spots, all of which go stale together:
+ - `:161` — the prose enumeration `(Text, Number, YesNo, Date, or a list of them)`.
+ - `:165`–`:174` — the conversion table. Add a `Time` row after `Date` and a `Time[]` row after `Date[]`, keeping the singular-then-plural grouping the table already uses.
+ - `:178` — the fidelity-guard paragraph. Add that `Time` needs no such guard, and why (the offset rides inside the time itself, so nothing is dropped). Stating it here is what keeps the next reader from filing the asymmetry as a bug.
+- [x] **3.2 — `CHANGELOG.md`,** a `### Fixed` entry under the existing `## [Unreleased]`. Frame it as the gap it is — `Time` was introduced after the matrix was written and was never added to it — and mention that the plural `Time[]` form is covered too. No version bump, no new heading.
+- [x] **3.3 — `make agent-check`.** ⚠ The auto-fixer runs inside this target and will keyword-only an ungranted positional subject; nothing in this change adds a new `def`, so there should be nothing to grant — if the check reports one, stop and look rather than accepting the rewrite.
+- [x] **3.4 — `make agent-test`,** the full suite, before the branch is considered done.
+
+### 🔶 Checkpoint — pipelex side complete
+
+Stop here and report. Before stopping: tick the boxes above, record under this checkpoint anything that deviated from the design (a line number that had moved, a test that needed a shape the plan did not anticipate, a doc spot the plan missed), and commit so the stop point is a clean tree. Then state plainly that Phase 4 is outstanding and lives in another repo — the change is *not* shippable until it lands, because the plugin's skills would be telling agents that `Time` does not convert while the runtime converts it.
+
+**Reached 2026-08-13. Phases 1–3 complete, `make agent-check` and the full `make agent-test` both green, tree committed.**
+
+Deviations from the design, all minor:
+
+- **A fifth enumeration site the plan did not list.** Beyond the four docstrings in the composer, the *test fixture* module `models_for_pipe_compose.py` carries the matrix in a section-header comment (*"TextContent -> str, NumberContent -> float, YesNoContent -> bool, DateContent -> date"*). It goes stale the same way and was updated. Nothing else in the tree enumerates the matrix — `grep`ed for the wording across `pipelex/`, `docs/` and `tests/`.
+- **Names chosen for the two holders:** `StartTimeHolder.start: time` (singular) and `SlotTimesHolder.slots: list[time]` (plural). Both are ≤ 18 chars so the `.mthds` concept block's column alignment was preserved untouched. The plural fixture puts the UTC offset on the *middle* item, so a list extraction that dropped it would fail on one item and not the others.
+- **Line numbers were all accurate** — nothing had moved since `c0cefb6af`.
+- **2.5's predicted asymmetry held, with one wording correction.** The singular case is not *silent*: the wrapper does reach the field, but `compose()`'s own field-type summary catches it and names it — `start: TimeContent (expected time) <-- MISMATCH`, `time_type`. The plural case failed exactly as described, per-item `slots.0/1/2: time_type` against `{'time': datetime.time(...)}` dicts, having fallen through all four `_validate_item_compatibility` cases. Both traces confirm the tuple entry in 1.2 is load-bearing.
+- **No drift contract fired,** as the design predicted — `make drift-check` passes untouched, no `make drift-ack` in this change.
+
+---
+
+## Phase 4 — the cross-repo follow-up (in `mthds-plugins/`, NOT this worktree)
+
+Doc-only, and mandatory: `templates/skills/shared/mthds-reference.md.j2:357` names the convertible natives as `Text`, `Number`, `YesNo`, `Date`. That line is accurate against today's runtime and wrong the moment Phase 1 ships.
+
+- [ ] **4.1 — edit the template**, not the generated files. `templates/skills/shared/mthds-reference.md.j2` is the source; `mthds/`, `mthds-dev/`, `mthds-codex/` and `mthds-sandbox/` are build outputs.
+- [ ] **4.2 — `make build`**, which regenerates all four targets. Verify the four generated `skills/shared/mthds-reference.md` copies moved.
+- [ ] **4.3 — check the neighbours before assuming one line is enough.** Phase 0 of the native-concepts plan found `Time` missing from *every* native enumeration in that repo, not the two files it expected. Grep the templates for the construct-conversion wording rather than trusting this list.
+- [ ] **4.4 — changelog** in `mthds-plugins`.
+- [ ] **4.5 — our internal integration suite** (not open core; its checkout lives in the workspace-level private notes). Required by the workspace rule whenever `mthds-plugins/` is touched: `make build && make agent-test` there, Docker running. ⚠ Known trap recorded during Phase 0: these tests require the local `mthds-js` checkout to be at or ahead of the published npm `mthds` version, or `update-check` assertions fail for reasons unrelated to your change. Fast-forward `mthds-js` first if a `mthds` release has landed recently.
+
+## Deliberately not in scope
+
+- **`test_pipe_llm_time_output_path.py`** (OQ-2). It is an `inference`-marked live-model test on a path this change does not touch. Deferred on purpose — do not fold it in to "finish `Time`". The plural test in 2.2 is *not* this; it is `dry_runnable` and covers the tuple entry.
+- **A `DateContent → time` arm** — see 1.3.
+- **Any release, version bump, or `/runtime-cascade`.** Nothing on the wire changes; this rides the next ordinary pipelex release.