Task 2: fluxer-proto primitives (#2) #29
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "task/2-proto-primitives"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
What this builds
The
fluxer-protoprimitives from Foundation plan Task 2 (spec section 3.2):Snowflake(pub u64): serde as a decimal string,FromStr,Display,timestamp()/timestamp_millis()usingFLUXER_EPOCH = 1_420_070_400_000and a 22-bit shift.Timestamp: RFC 3339 viatime; any offset or fractional precision is accepted and normalised to UTC milliseconds, written asYYYY-MM-DDTHH:MM:SS.mmmZ(theDate#toISOString()form).Permissions:bitflagsoveru64, the 39 flags copied from the fork'spackages/constants/src/ChannelConstants.ts, serde as a decimal string. Unknown bits are preserved (const _ = !0).ChannelType,MessageType(integers withUnknown(u16)),UserStatus(strings withUnknown(String)), each round-tripping unknown values unchanged.How it was tested
crates/fluxer-proto/tests/primitives.rs: the five tests the plan names plus timestamp, message type and user status tests, and proptests for snowflake, permissions, timestamp and enum round-trips (13 tests). Written first and seen failing (first commit), then passing.cargo xtask ciis green locally on Linux.Deviations from the plan
Cargo.tomlandCargo.lockare outside the task's Files list:bitflags,proptestandtimewere added to[workspace.dependencies](all three are named in the plan's Tech Stack) and wired intocrates/fluxer-proto/Cargo.toml.crates/fluxer-proto/README.mdupdated, as CLAUDE.md requires.Snowflake::timestamp_millis(),Timestamp::{from_unix_millis, unix_millis, as_offset_date_time, from_offset_date_time, UNIX_EPOCH},ParseSnowflakeError,ParseTimestampError,UserStatus::as_str,From<u16>/Into<u16>on the integer enums.SnowflakeandPermissionsalso accept a bare non-negative JSON integer on input (they always serialize as strings).UserStatus::Unknowncarries the rawStringso it round-trips; the plan writes it as bareUnknown. ConsequentlyUserStatusisClonebut notCopy.Timestampdeserialization of a non-RFC-3339 string is an error (not a panic); models in Task 3 decide per field whether that is fatal.Closes #2
🤖 Generated with Claude Code
Independent review of Task 2 (proto-primitives) at
9a52d94Verdict: CHANGES REQUESTED (1 blocking, 3 minor). Local
cargo xtask ciin a clean review worktree: green (screenshot step skipped by design; remote runners not checked).Blocking
B1. Server data can panic the client:
Timestampparse of an RFC 3339 string whose UTC instant falls past year 9999 (crates/fluxer-proto/src/timestamp.rs:62,from_offset_date_time)OffsetDateTime::parse(.., &Rfc3339)accepts a local date of 9999-12-31 with a negative offset.from_unix_timestamp_nanos(truncated)then fails (UTC year 10000) and the fallbackvalue.to_offset(UtcOffset::UTC)panics withlocal datetime out of valid range. Reproduced through serde:This violates the Global Constraint / CLAUDE.md rule "Server data must never panic the client"; any message, channel or read-state payload carrying such a string would take the client down. The comment above the fallback ("can only leave the valid range at its very first millisecond") is wrong: the failing case is the upper end with a non-UTC offset. Fix: make the conversion fallible (
checked_to_offset/ returnNone) soFromStryieldsParseTimestampError, and decide what the infallibleFrom<OffsetDateTime>does (saturate, or becomeTryFrom). Add these two strings totimestamp_roundtrips_rfc3339as must-be-Err-not-panic cases.Minor
M1.
UserStatus::Unknown(String)deviates from the Interfaces block (enums.rs), which lists a bareUnknown.UserStatusis therefore notCopy, andUserStatus::Unknownas a unit pattern/expression will not compile in Tasks 3/4/11. Defensible (round-trips the raw value, consistent with the integer enums) and disclosed in the PR body, but the plan's Interfaces block should be updated so dependent tasks see it; otherwise revert to the bare variant.M2. Integer enums reject values above
u16::MAX(enums.rs,u16::deserialize). A future channel/message type of 70000 is a deserialization error for the whole enclosingChannel/Messagerather thanUnknown. Not a panic and the plan specifiesUnknown(u16), so within spec; worth knowing for Task 3/4 error handling.M3.
Timestampnormalises on output (always UTC, exactly 3 fractional digits; also accepts lowercasez, a space separator and a:60leap second, which is clamped to.999). Fine for a JS server, but Task 3's byte-for-byte fixture round-trip only holds for fixtures inDate#toISOString()form.Verified
snowflake_roundtrips_as_string("1554245914976059392"both ways),snowflake_timestamp_uses_fluxer_epoch,permissions_parse_decimal_string_bitfield("1024"hasVIEW_CHANNEL),channel_type_unknown_value_preserved(777 both ways), proptestsnowflake_string_roundtrip.1554245914976059392 >> 22 + 1420070400000 = 1790631502623= 2026-09-28T21:38:22.623Z;2026-09-28T19:17:20.326Z= 1790623040326 ms. Both correct.Snowflake(pub u64)(string serde,FromStr,Display,timestamp() -> Timestamp),FLUXER_EPOCH = 1_420_070_400_000, 22-bit shift,Timestamp,Permissions: u64as decimal string,ChannelType,MessageTypewithUnknown(u16), all re-exported from the crate root.Permissions: 39 flags, names and bit positions identical to the fork'spackages/constants/src/ChannelConstants.ts;ChannelTypeandMessageTypevalue sets andUserStatusstrings match the fork constants.#[serde(untagged)]enum (relevant to Task 3'sLoginResponse).bitflags,time,proptest) are named in the plan's Tech Stack;cargo denygreen. Commits carryRefs #2and the trailer; PR targetsfoundationand hasCloses #2.Review round 1, addressed in
281ce70.cargo xtask ciis green locally.Blocking: out-of-range timestamp panics (
timestamp.rs) — fixed.Timestamp::from_offset_date_timenow returnsOption<Timestamp>; theto_offsetfallback is gone.From<OffsetDateTime>is replaced byTryFrom<OffsetDateTime>with a newTimestampRangeError(re-exported from the crate root).FromStrandDeserializereturnParseTimestampError/ a serde error.Timestamp::from(odt)no longer compiles; useTimestamp::from_offset_date_time(odt)ortry_from.from_unix_millisincluded. It previously accepted negative years, which would have been written as a string that is not RFC 3339.timestamp_out_of_range_is_error_not_panic: both strings from the finding (9999-12-31T23:59:59-23:59,9999-12-31T23:59:59.999-00:01) plus the two mirror cases at year 0000 must beErrthroughFromStrand through serde; the edges of the range still parse.Minor:
UserStatus::Unknown(String)vs the Interfaces block (enums.rs) — kept theString(it round-trips the raw value, like the other wire enums) and updated the Task 2 Interfaces block indocs/superpowers/plans/2026-11-11-foundation.mdto sayUnknown(String),ClonenotCopy, matched asUserStatus::Unknown(_). Same note added to theenums.rsmodule docs and the crate README. This is the one file outside the crate that the commit touches.Minor:
ChannelType/MessageTypeabove 65535 (enums.rs) — no code change; behaviour is as the plan specifies and was already pinned by a test (json!(70_000)isErr). Documented in theenums.rsmodule docs and the README, and deferred to follow-up #30 to decide whether to widen the fallback.Minor:
Timestampoutput normalisation (timestamp.rs) — no behaviour change. Documented on the type and in the README that onlyDate#toISOString()-form strings round-trip byte for byte, so Task 3 fixtures must use that form. New testtimestamp_output_is_normalised_to_to_iso_string_formpins the lowercaset/z, space separator, offset, extra fraction digits and:60leap second (written back as:59.999) cases.Independent review of Task 2 (proto-primitives) at
281ce70Verdict: APPROVE — no blocking findings; local
cargo xtask cigreen.Checked, in order:
crates/fluxer-proto/tests/primitives.rsand assert the plan's values:snowflake_roundtrips_as_string("1554245914976059392"<->Snowflake(1554245914976059392)),snowflake_timestamp_uses_fluxer_epoch(FLUXER_EPOCH == 1_420_070_400_000, 22-bit shift; sample id -> 1790631502623 ms, recomputed independently),permissions_parse_decimal_string_bitfield("1024"containsVIEW_CHANNEL),channel_type_unknown_value_preserved(777->Unknown(777)->777), proptestsnowflake_string_roundtrip. 15 tests pass.Snowflake(pub u64)(string serde,FromStr,Display,fn timestamp(&self) -> Timestamp),FLUXER_EPOCH,Timestamp(RFC 3339 viatime),Permissions: u64as decimal string,ChannelType/MessageType+Unknown(u16),UserStatus+Unknown(String)all present and re-exported from the crate root. Compared against the fork: all 39 permission bits, the 13 channel types, 13 message types, 5 statuses and the epoch matchChannelConstants.ts,StatusConstants.ts,Core.ts.fluxer-protodepends only onbitflags,serde,serde_json,thiserror,time(+proptestdev);cargo denygreen; no I/O; no tokens or secrets. Nounwrap/expect/panicking path on server data insrc/: the earlier out-of-rangeTimestamppanic is fixed (conversion goes throughunix_timestamp_nanos+ a range filter, covered bytimestamp_out_of_range_is_error_not_panic).cargo xtask ciin the review worktree: all steps passed (screenshot step skipped becauseFLUXER_SCREENSHOT_TESTSis not 1). Remote runners not checked.Findings:
crates/fluxer-proto/src/timestamp.rs: the public API differs from what a later task might assume:From<OffsetDateTime> for Timestampis nowTryFrom, andTimestamp::from_unix_millis/from_offset_date_timereturnOption. The plan's Interfaces block only says "Timestamp(RFC 3339 viatime)", so nothing is broken, but Tasks 3/4/10 should be told (the README covers it).crates/fluxer-proto/src/enums.rs:ChannelType/MessageTypewire values outsideu16fail deserialization of the enclosing object rather than mapping toUnknown. Against the letter of "unknown enum values map to anUnknownvariant" only for values the server does not produce today; documented and tracked in #30. Not a panic.docs/superpowers/plans/2026-11-11-foundation.md: the branch edits the plan (Task 2 Interfaces:UserStatus::Unknown(String),ClonenotCopy). The edit is accurate and is the only change outside the crate; the integrator should make sure Tasks 3/4/11 read the updated line.Claude Fable 5.2whileCLAUDE.mdand the plan's Global Constraints still sayFable 5.1. Matches the model the run was asked to use; the two documents should be updated in their own change.281ce7044736d484c534Integrator: rebased onto foundation (
6a1dd09). Windows CI failed on the rebased head withfailed to remove file ...\\debug\\xtask.exe: Access is denied(not caused by this task; see #32). Added689e9c9, a CI-only workaround in.forgejo/workflows/ci.yaml(Windows job runs xtask from its own target dir). Root cause tracked in #32.