fix(firestore)!: decode missing keys for Optional and server-stamped fields

[fwal]

Fixes a regression from the Effect v4 port: Firestore.Optional database variants rejected a missing document key with SchemaError: Missing key, so getById/queries/triggers failed on real documents that omit optional fields.

Changes

• Optional select/insert/update use Schema.OptionFromOptionalNullOr(s, { onNoneEncoding: null }). Missing key, null and undefined decode to Option.none(); Option.none() still encodes as null.
• OptionalDeletable.update uses OptionFromOptional(Union([s, DeleteInstance])): decodes a missing key, encodes Option.none() as an omitted key instead of undefined. Its fieldEvolve overload type is corrected to match runtime.
• DateTimeInsert / DateTimeUpdate / ServerDateTime insert/update variants target Schema.optional(DateTimeUtc) and encode via SchemaGetter.transformOptional, so the key can be omitted for a server timestamp. createdAt: undefined is no longer required.
• Regression test for models spreading struct fields with a decoding default (Schema.optionalKey(s).pipe(Schema.withDecodingDefault(...)), the v4 form of optionalWith(..., { default })).
• MIGRATION.md and AGENTS.md updated.

Breaking (type-only)

Encoded type of Optional fields moves from NullishOr<S> to optional(NullOr<S>); the key becomes optional in Model.Encoded. Annotations using Schema.OptionFromNullishOr<...> must switch to Schema.OptionFromOptionalNullOr<...>. A merge update whose only field is Option.none() on an OptionalDeletable now fails invalid-argument (empty payload).

Closes #29

🤖 Generated with Claude Code

https://claude.ai/code/session_01UTvaTdYRhJ8MdaKxQ19miS

---

Generated by Claude Code

[greptile-apps]

Greptile Summary

This PR restores missing-key decoding for optional Firestore fields and allows server-stamped fields to be omitted from write inputs.

• Optional decodes missing keys, null, and undefined to Option.none() while continuing to encode None as null.
• OptionalDeletable preserves omitted keys through nested update encoding.
• Regression tests cover optional fields, server timestamps, nested updates, and decoding defaults.
• Changes since the previous review clarify when to use Schema.optionalKey for plain optional fields.

Confidence Score: 5/5

The PR appears safe to merge, with no new actionable findings and the previous nested-update omission issue fixed.

The nested leaf encoder now distinguishes an omitted property from a present value, and payload assembly skips omitted leaves. Regression coverage includes dotted updates, merge updates, and deletion. The documentation-only changes since the previous review introduce no established blocking failure.

Important Files Changed

Filename	Overview
packages/effect-firebase/src/lib/firestore/model/optional.ts	Updates optional-field schemas and types to support missing database keys.
packages/effect-firebase/src/lib/firestore/model/datetime.ts	Encodes omitted server-stamped fields as server timestamp sentinels.
packages/effect-firebase/src/lib/firestore/model/repository.ts	Preserves encoded key presence and skips omitted nested update leaves, addressing the previous finding.
packages/effect-firebase/src/lib/firestore/model/repository.spec.ts	Adds regression coverage for nested omission, delete sentinels, and spread decoding defaults.
packages/effect-firebase/AGENTS.md	Clarifies optional-key declarations and decoding-default usage.
packages/effect-firebase/MIGRATION.md	Documents changed optional-field types, omission semantics, and plain optional-field guidance.

_{Reviews (3): Last reviewed commit: "docs(firestore): recommend Schema.option..." | Re-trigger Greptile}