fix(act): revive dates on read instead of re-validating the payload

[Rotorsoft]

Closes #1594.

An event that had both a sensitive() field and a date in its schema could not be read at all. query, query_array and load all threw, and because running a command loads the state first, the stream stopped accepting writes too. This fixes that and several related problems found on the way.

What went wrong

When an event's schema mentions a date anywhere, the framework builds a copy of that schema and runs it over the event's data on every read. Dates do have to be revived — JSON has no date type, so a Date is stored as text and something has to turn it back.

The trouble was that the copy listed every field and ran as a validating parse, so each read re-checked the whole payload. That check was never needed: events are validated when they are committed, so anything in the store has already passed its schema once.

And it did more than waste time. Fields marked sensitive() are moved out of data into a separate pii field on write, but the copy still listed them as required. The framework rejected data it had written itself.

What changed

The copied schema now names the date fields and nothing else. Everything else passes through untouched.

That single idea is what makes reading tolerant, rather than a growing list of exceptions. A field that is not a date is simply not described, so none of these are the schema's business any more: a sensitive() field living in pii, a field added to the declaration after an event was written, a field since removed. The dates themselves are optional for the same reason — absent is not wrong. If a payload still cannot be revived, the read hands back what is stored instead of throwing.

Unions are the exception, and they need their fields. Zod picks a union variant by trying each until one matches. A variant reduced to its dates matches almost any payload, so the first option wins and the variant that declared the date is never tried — meaning a union event's dates were not revived at all, and a sibling's payload could be read under the wrong variant's rules. Variants therefore keep their fields (optionally), so a discriminator can still reject a payload that is not its own.

This is not laziness, and narrowing it was measured before being rejected. Two variants told apart by the type of a field rather than a literal:

	variant A (at is a date)	variant B (at is a string)
fields kept (shipped)	Date	String
fields narrowed	String — not revived	String

There is no smaller subset that still discriminates, because which fields do the discriminating is not knowable — a literal usually does it, but a field type can too. A test pins this so nobody tidies it away.

The pii sidecar is revived too, but only for readers allowed to see it. Without this, a disclosed sensitive(z.date()) arrived as text beside an ordinary date that was a Date. It is skipped for handler readers, which drop pii outright, and for query/query_array, which carry no actor and always deny — so plaintext is no longer converted just to be overwritten with [REDACTED]. The gate still decides; the guard never calls the disclosure predicate, so a caller's code runs exactly once.

Each question is answered by the module that owns it. Working out where a schema's dates are is a Zod concern, not an event one, so internal/date-reviver.ts owns it and exports exactly one function. Which fields are sensitive was already internal/sensitive.ts's subject, but the event builder walked the shape itself to get each field's schema — pii_schemas now returns them and pii_fields is its keys, so there is one walk instead of two. event_tags composes the two answers and no longer touches .shape, .options or _zod at all.

The walk also now descends through .default(), .catch(), .readonly(), .nonoptional(), .prefault() and tuples, which previously left a date inside them as text. .default() is common enough that this was likely to be hit.

Known limits

Dates inside a z.intersection(...) or a z.lazy(...) are not revived — those constructs build no reviver and the value stays text. Unchanged from before this PR, and it is the documented fallthrough ("a construct this doesn't recognise contributes no date"); lazy in particular can be recursive, so descending into it needs care. Verified rather than assumed: z.discriminatedUnion reports itself as a plain union and is handled.

pii_schemas merges union variants first-wins, so a key sensitive in two variants with different declared types is revived using the first variant's schema. That matches the previous behaviour and no test exercises it.

What it costs

About 0.07µs per event read. A cold load on Postgres is 545µs (libs/act-pg/PERFORMANCE.md:1430), so roughly 0.01% of a read.

Worth stating plainly, because naming only the date fields is slower in a micro-benchmark than listing them all — 0.272µs against 0.200µs on a six-field payload. Zod charges more for a key it was not told about than for one it validates, so leaving fields out moves them onto the more expensive passthrough path.

An earlier version of this branch kept every field declared for exactly that reason, which was optimizing the wrong thing. The same PERFORMANCE.md table records a hand-rolled walk that was faster than the shipped Zod parse (0.188µs vs 0.285µs) and was rejected anyway, because correctness and maintainability beat a tenth of a microsecond. Same trade, same answer.

What was considered and rejected

superjson and devalue solve the general "JSON lost my types" problem by carrying type metadata beside the payload, and superjson is the usual answer in the TypeScript ecosystem. It is the wrong layer here: it changes the stored format, so existing events carry no metadata and external SQL readers would see a wrapped shape.

Zod 4 codecs (z.codec(z.iso.datetime(), z.date(), …) with z.decode) are the most principled option and were tested against the installed 4.4.3. z.decode still validates the whole payload — a field added to the declaration after an event was written is rejected, the exact failure this PR is about — and a plain z.date() is not decodable from a string, so adopting codecs would mean every Act user rewriting their event schemas. Naming only the date paths is what avoids re-validation, and it works the same whichever coercion primitive sits at the leaves.

Test plan

• 24 cases across libs/act/test/schema-dates.spec.ts and libs/act-sqlite/test/read-schema-dates.spec.ts
• All three symptoms, every wrapper, a payload predating the declaration, a date field holding junk, and the dateReviver revives by shape, not by schema, so a z.string() field comes back as a Date #1556 guard
• Five union cases, including both variant orderings and a union discriminated by field type rather than a literal
• The adapter tests run on SQLite deliberately — InMemory keeps the original objects and never turns a date into text, so it cannot see any of this
• pnpm test — 3622 passing
• 100% coverage on statements, branches, functions and lines
• pnpm typecheck, biome clean, architecture spec passing (it enforces that pii_* helpers stay reachable only from sensitive.ts and the event builder)
• CI green
• Review

How this relates to #1556

#1556 was the opposite problem: adapters revived dates by looking at the shape of every string, so an ISO-looking z.string() came back as a Date. #1570 fixed it by letting the schema decide, which was right, and this PR keeps that. Zod still does the walking, so nesting, arrays, records, unions and wrappers are handled by the engine rather than by a traversal of our own that would drift as Zod grows. A test pins the #1556 behaviour so it stays fixed.

Stability charter impact

Additive and internal. EventTags gains date_reviver and pii_date_reviver (replacing parse), the schema walk moved to internal/date-reviver.ts, and sensitive.ts gains pii_schemas. All @internal. The one publicly reachable name involved, pii_fields (re-exported through types/schemas.ts and used by act-http's OpenAPI emitter), keeps its exact signature — it is now implemented as the keys of pii_schemas. The public dateReviver in utils.ts is untouched. No builder method, IAct method, port, lifecycle event or exported type changed. Behaviour changes only in that reads which used to throw now succeed.

rfc-gate: exempt — the stability snapshot grew only because it captures source text, and what grew is doc comments plus an internal module. No public surface was added.

Found by

Debug wave 21, reproduced in the main loop before filing. The union bug was found while reviewing this branch, not by the wave.

[github-actions]

🎉 This PR is included in version @rotorsoft/act-tck-v1.36.15 🎉

The release is available on:

• @rotorsoft/act-tck-v1.36.15
• GitHub release

Your semantic-release bot 📦🚀

[github-actions]

🎉 This PR is included in version @rotorsoft/act-v1.31.15 🎉

The release is available on:

• @rotorsoft/act-v1.31.15
• GitHub release

Your semantic-release bot 📦🚀