[cabcookie]

What

A plugin can declare a custom field of type datetime:

[fields.occurred_on]
type  = "datetime"
on    = ["note"]
label = "Occurred on"

• Accepted: RFC 3339 with a time zone (Z or ±hh:mm), fractional seconds allowed.
• Refused (validation, naming the field): a plain date, a local time without an offset, non-RFC 3339, a UTC year outside 0000..=9999.
• Stored: the same instant in UTC at whole seconds, YYYY-MM-DDTHH:MM:SSZ (offset applied then discarded, fractions truncated). 2026-10-12T10:30:00.9+02:00 -> 2026-10-12T08:30:00Z.
• Cleared by an empty value, like every custom field.

One fixed shape makes text order equal chronological order, so the derived ranking comparator (of = { field = "..." }), the hosted fold and any SQL sort order datetime values correctly with nothing type-aware downstream. Normalization happens once at the write seam (validate::datetime from prepare_custom_set).

nxf schema --json / MCP flow_schema report "kind": "datetime"; --set and MCP flow_create/flow_update validate (MCP set param docs mention it).

Facade

facade: breaking — plugin::FieldType gains Datetime and is now #[non_exhaustive] (an exhaustive external match needs a wildcard arm; later types become additive). New validate::datetime. app-foundations follows with 41j0.bm81.

Tests

• validate::tests::datetime_* (normalization, fractions, refusals, UTC year range)
• plugin::tests::a_datetime_field_parses_validates_and_reports_its_kind
• facade tests/write.rs: create/update normalization + clear; refusal writes nothing
• facade tests/engine.rs: Engine::update -> show_value/custom_fields_bulk, schema kind
• facade tests/derived_ranking.rs: related ... of = { field = "met" } ranks chronologically across offsets (min/max, asc/desc)
• nxs MCP custom_field_tests: create/update through the handlers
• plugin-probe ky26_file_consumer: schema --json kind + create (file-fixture gains an optional produced_at datetime)
• fold-ddb records_differential: served board holds the same UTC instant as the replica

Docs: spec plugin-custom-fields.md §5.1 (+ TB-CF-3 note), guide plugins.md EN/DE "Declaring custom fields".

🤖 Generated with Claude Code

https://claude.ai/code/session_016q5uMUkZJQW4fckJoA3FME

[cabcookie]

Contained in #63, which folds #61 and #63 plus the review mitigation and was merged in one squash.