DEV Community: hiro@

A multi-device push rollout remains incomplete while old logout behavior survives

hiro@ — Sat, 17 Oct 2026 01:48:27 +0000

A server can store multiple push tokens per user while an old application's logout still removes every device registration. The new API behavior alone does not describe the state of a rollout.

This investigation combined SquadNote's old and new APIs with old and new logout methods. Its focus is the combinations that can remain in use and the evidence needed to call the migration complete, rather than the registration and deletion implementation itself.

The source versions are circle-hub at 0cda1e8 and the parent of change ad0a669. Tests ran locally on September 11, 2026. No OTA update or notification to a physical device was sent.

A migration can remain even without a new table

The implementation specification says the existing token table and unique-token constraint suffice without a database migration.

Before the change, registering a previously unregistered token also removed existing tokens for that user. Registering iOS and then Android left only the later registration.

The updated API upserts by token and preserves another device's registration. However, it retains unregisterAllPushTokens for compatibility.

The mobile change must also reach clients for ordinary logout to remove only that installation's tokens. Having an adequate server schema and having every caller use the new deletion scope are different conditions.

Combine both server versions with both deletion methods

In disposable copies, the actual before-and-after tRPC routers were connected to the same kind of local libSQL database. An authenticated synthetic user registered an iOS value followed by an Android value. These were test strings, not actual Expo Push Tokens.

The comparison then selected either the old caller's all-device deletion or the new caller's device-specific deletion. It exercised the API calls rather than running the application UI and network end to end.

Server	Deletion method	After 2 registrations	After Android-side logout
Before change	Delete all	Android only	0 rows
Before change	Delete device	Android only	0 rows
After change	Delete all	iOS and Android	0 rows
After change	Delete device	iOS and Android	iOS only

All four cases matched their assertions. Adopting only the new logout method cannot make the old server retain both destinations. Conversely, the new server still removes both if all-device deletion is called.

The “old server + device deletion” case reaches 0 because registering Android already removed iOS. Device-specific deletion did not itself remove the iOS row. Inspect both the post-registration and post-logout states instead of only the final count.

Distribution does not restore deleted registrations

The test also registered iOS again after logout and confirmed that its row existed. That was the result of another registration call with the required input. Updating the server did not automatically reconstruct deleted rows.

A rollout therefore needs to distinguish distributing new code, applying it, and executing registration:

Distribute the new code
  ↓
The target device downloads and applies it
  ↓
The device executes registration
  ↓
The required destinations exist on the server
  ↓
Verify logout preserves the other device

This is a proposed verification sequence. The investigation did not collect the rollout stage of actual user devices. It does not establish that everyone updated or that all registrations were restored.

Matching runtimeVersion labels are insufficient evidence

The specification calls for updating Web/API first and then delivering compatible changes to both iOS and Android. It also records different native dependency configurations in the targeted builds for the two platforms.

Expo's runtime-version documentation requires updates to be compatible with the native code embedded in a build. Assigning the same identifier manually does not make different native configurations identical.

A rollout record can connect the API commit, each platform's build and runtimeVersion, the applied update, and the registration outcome. This article did not change delivery settings or infer successful distribution from local tests.

Automated checks and the remaining receipt checks

The 4 additional cases passed alongside 8 existing registration, deletion, and sending tests, for 12 successful tests. The environment was Node.js v24.15.0 and Vitest 4.1.4. Tests used in-memory libSQL and the actual router code. External HTTP for notification sending was mocked.

The reproduction runner and compatibility matrix test are recorded.

These checks establish how the specified calls change database registrations. They do not cover physical-device permissions, delivery after Expo accepts a message, OS notification presentation, or recovery from offline operation.

The original specification's physical-device checklist is also unchecked at the inspected revision. It calls for applying updates to both platforms, receiving on both devices, and receiving only on the remaining device after one logs out. A documented procedure is not evidence that it was executed.

A completion record should include the server test results, remaining callers, update application, recreated registrations, and actual receipt checks.

Consolidating Codex TODOs in Plane without merging different deliverables

hiro@ — Fri, 16 Oct 2026 01:29:31 +0000

Suppose a TODO to explain joining a group through an invitation link appears in more than one conversation. Merging it into an existing ticket because the title sounds familiar could combine a carousel and a video into one task.

Consolidation works better when it identifies the target and deliverable. The same theme can require separate outputs. If a conversation continues existing work, decide where its new assumptions and remaining tasks belong.

This record compares SquadNote's Plane tickets with fixed Git documents on September 11, 2026. Some descriptions retain a Codex chat date. It is not an experiment in automatically extracting tasks from complete conversations, and no tickets were created or merged during the audit.

Separate matching themes by their deliverables

The production records include parent SQN-46 and children SQN-47 and SQN-48. Their abbreviated scopes differ as follows.

ID	Subject	Deliverable	Relationship
SQN-46	Instagram publishing series	Theme management and ongoing operation	Parent
SQN-47	Joining through an invitation link	Five carousel images, HTML/CSS, caption, alt text	Static version
SQN-48	The same joining guide	Vertical MP4, editable source, scene images, subtitles, cover	Video version

Both children cite Codex chat 2026-09-09, and the video refers to the static version. Their shared theme reflects adaptation to another format, rather than duplicate work.

The Git records preserve the same relationship. The static README links back to SQN-47, and the video README links to SQN-48. The audit also read the initial production commit 560e752, the audio-preview commit afcf45f, and the later operating documentation in e295f5c.

Combining the two would make a single Done state unable to express that the images are ready while the video's subtitles still need work. When wording recurs across conversations, compare the outputs first.

Preserve execution conditions in related parent and child tasks

Another pair, SQN-14 and SQN-27, both concern removing a legacy Turnstile compatibility bypass. Their distinction is an execution condition rather than a media format.

SQN-14 describes checking adoption of the updated app before removing the compatibility code. Its child, SQN-27, specifies final removal after reviewing legacy usage on or after 2026-09-10. The retrieved parent relationship matched the description.

Discarding the later TODO merely because both say "remove the old code" would lose the condition about allowing time for update notices to reach users. Treating them as independent implementation tasks could instead duplicate the same deletion.

The parent can be read as the background and overall conditions, with the child specifying when to execute. Both were Done when retrieved, but production logs and behavior after removal were not rechecked. The state is an observed field; correctness of the code removal requires separate evidence.

Reduce a candidate to one line before importing it

Before creating a ticket from a conversation, rewrite its candidate task in this form:

Service / Target of the change / Deliverable / Condition for accepting it

For the joining guide, that becomes "SquadNote / invitation guidance / vertical video / current flow, subtitles, and visuals agree." Search existing tickets with that description, then read their bodies and relationships rather than only their titles.

A proposed way to handle the matches is:

If target, output, and acceptance conditions match, collect the additional information in the existing ticket.
If the theme matches but the output differs, retain a separate related task.
If it is an independently verifiable part of a larger plan, consider a parent-child relationship.
If it changes a completed deliverable, retain the reason and target version before deciding whether to reopen the work or create a follow-up.

Text similarity can help locate candidates. It cannot reliably establish that subtitle acceptance conditions or a rollout prerequisite match.

When several conversations contribute to one candidate, append their dates and relevant decisions instead of replacing the source with the latest one. This does not require copying complete chats into the description. Leave out secrets and verification invitation URLs, and retain the information needed to follow the decision.

A Done state can hide later preparation work

SQN-48 was Done at retrieval time. The fixed Git publication review still records work such as generating publication audio, synchronizing subtitles to speech, and verifying actual interactions.

Those two observations do not prove the original ticket was closed incorrectly. Its scope may have changed between initial production and later publication preparation. They do show that Done alone is insufficient evidence that the latest asset is ready to publish.

During consolidation, check for subsequent changes before treating a completed ticket as requiring no action. In this example, a handoff candidate can retain:

Sources: The video ticket and publication review at a fixed commit
Existing assets: A silent preview master and editable production sources
Remaining work: Publication audio, subtitle synchronization, interaction and posting checks
Completion evidence: Final-version verification and a publication record after approval

This is a handoff example derived from the records, not a newly created ticket. The audit did not publish anything or generate paid media.

Consolidating conversation TODOs means identifying which existing deliverable should advance, and from which recorded state. In this case, the static and video outputs needed to remain distinct, while the latest Git document supplied the remaining publication preparation work.

Verify authentication recovery before treating Configuration as the root cause

hiro@ — Thu, 15 Oct 2026 02:03:05 +0000

A return URL containing error=Configuration suggests a configuration mistake. Yet the inspected Auth.js version also produces that destination when a PKCE cookie is missing. The user-facing classification does not identify the cause by itself.

This investigation read SquadNote's recovery implementation and reran tests against its actual Auth.js dependency. It examines rejection, retry navigation, and diagnostic evidence before drawing a causal conclusion.

The source is circle-hub at d116e8a, checked on September 11, 2026. No production authentication logs or user histories were collected. This is an account of recovery code and rerun verification, not proof of a production incident's cause or resolution.

Distinguish the internal error from Configuration

Auth.js's InvalidCheck reference covers PKCE, state, or nonce checks that cannot be performed. Unavailable cookies can produce it, as can configuration issues.

The repository regression test resolves @auth/core through the application's next-auth dependency. It does not substitute a separately installed latest release.

A synthetic callback without its PKCE cookie produced:

Observation	Result
HTTP status	302
Redirect destination	`/sign-in/error?error=Configuration`
Internal type passed to the logger	`InvalidCheck`

The fixture deliberately omitted the cookie, so its cause is known. Seeing the same internal type in production would still require investigating why the cookie did not arrive. Expiration, another initiation, and browser behavior cannot be distinguished from that display alone.

First restore a path from failure to a fresh start

The recovery design record and history show the recovery screen in 061a5f2, repeated-submission protection in 2b88c31, and diagnostics in 7f180ad.

The recovery screen presents sign-in and public help without depending on auth() or the database. Displaying an authentication failure does not require successfully repeating the same authentication dependency.

Return destinations are restricted to safe paths on the same origin. Tests preserve invitation-page returns while rejecting external redirection and authentication-page loops. The original callback URL is not reused unconditionally.

Two new initiation requests sent to the actual Auth.js implementation produced different PKCE challenges, S256, and fresh PKCE cookies. However, the initiation fixture uses the internal CSRF-skip option. It does not verify browser CSRF protection or a round trip through the OAuth provider, and no production setting was changed to disable CSRF checks.

Reject a second start before React rerenders

Disabling a button visually can leave a window before React rerenders in which another button can be pressed. The implementation uses a synchronous guard shared by Google and Apple initiation on the same screen:

export function createSubmissionGuard() {
  let submitting = false;
  return {
    acquire() {
      if (submitting) return false;
      submitting = true;
      return true;
    },
    reset() { submitting = false; },
  };
}

Tests against the actual guard reject immediate reacquisition, allow acquisition after the reset used for failure or history restoration, and keep separate instances independent.

Its scope is repeated submission from one screen. It does not serialize initiation across tabs or browsers, nor remove every possible cause of missing cookies.

Correlate how far the flow progressed

The diagnostics investigate initiation and callback boundaries without storing authentication values. The principal events mean:

Event	What it establishes
`auth.sign_in_started`	A start request occurred
`auth.authorization_redirect`	Initiation generated a destination
`auth.callback_received`	A callback arrived
`auth.sign_in_succeeded`	Auth.js emitted its signIn event
`auth.server_error`	Failure and diagnostic information were recorded

Initiation and destination generation do not mean authentication succeeded. In particular, the server action's cookiesAfterStart observes the cookie jar at that time. Existing cookies can be present, so presence alone does not establish fresh issuance.

requestId identifies a failing request; attemptId supports correlation with initiation. The latter marker is client-originated diagnostic information and does not authorize authentication. It represents the browser's most recent initiation, so it does not prove the same OAuth transaction across multiple tabs.

Absent, expired, or provider-mismatched markers can prevent correlation. Record why correlation failed instead of rephrasing that as “no initiation happened.”

Add diagnostics without weakening authentication checks

Diagnostic tests verify that synthetic sensitive values, including cookie values, authorization codes, tokens, raw User-Agent strings, and IPs, do not appear in logs. Cookie observations retain only presence for specific names, and paths are restricted to authentication routes.

Tests also check isolation between concurrent requests, preservation of authentication responses when diagnostics or notifications fail, and preservation of the original Auth.js response cookies. The change does not obtain successful logins by relaxing PKCE, state, or nonce requirements.

Alert suppression operates within a Worker instance; it is not a delivery guarantee across all distributed instances. The diagnostic cookie is not a session replacement either. Neither mechanism belongs in the decision that authentication has succeeded.

The 47 tests and the remaining environment checks

The run passed 47 tests across 8 files copied from the fixed commit. It used Node.js v24.15.0, Vitest 4.1.4, Next.js 15.5.15, next-auth 5.0.0-beta.25, and its Auth.js core dependency 0.37.2. The runner and results are preserved.

Some tests invoke the actual Auth.js implementation; others mock route or notification dependencies. Real Google or Apple accounts, Safari or embedded browsers, multiple tabs, and manual browser-cookie deletion were not tested in this run. Historical UI verification documented in the repository is also separate from these rerun results.

Verify the failure classification, fresh initiation, safe return destination, same-screen repeat protection, and the limits of log correlation in order. While the cause remains uncertain, record the conditions for retry and the questions requiring further investigation.

From 63 seconds to 60: checking a game trailer against its timeline and video files

hiro@ — Wed, 14 Oct 2026 02:22:13 +0000

Even a short game trailer fills up quickly with a title, combat, upgrades, bosses, and a destination to play. Removing a few seconds at the end does not change what viewers encounter first.

VOLT NOMAD's history retains an initial trailer configured for 63 seconds and a second version reorganized around 60 seconds. The change also moved combat to the opening. This article compares the code-defined sequence with the actual video files.

The investigation inspected fixed revisions and Git-tracked MP4 files on September 11, 2026. It did not regenerate the trailer or measure audience retention.

Combat began at 13 seconds in V1 and at the opening in V2

The initial capture code at bf5c7e7 begins with:

Configured interval	Initial content
0.0 to 3.5 seconds	Key art
3.5 to 8.0 seconds	Title screen
8.0 to 13.0 seconds	Route selection
13.0 to 22.0 seconds	Combat

The capture code containing V2 at f074703 opens with early combat followed by upgraded combat:

Configured interval	V2 content
0.0 to 4.5 seconds	Initial combat: click, damage, CHARGE
4.5 to 10.0 seconds	Upgraded combat
10.0 to 16.0 seconds	Gear tree
16.0 to 21.0 seconds	Route selection

The ordering in the code verifies a change toward showing what an action produces at the start. It does not establish an improvement in viewer understanding or view counts.

The useful editing decision is to reconsider which action belongs first before shortening every asset a little.

Use the interval table to drive capture

V2's beats array holds start and end times, a scene ID, captions, and other presentation data. Runtime code chooses the interval from elapsed time:

func beat_index_at(time: float) -> int:
    for index in range(beats.size()):
        if time < float(beats[index].end):
            return index
    return beats.size() - 1

Changing intervals configures the game state and presentation for capture. Reaching DURATION ends the process.

This function selects intervals by their end times. It does not separately use start times to create empty gaps. If one start differs from the preceding end, the table's description and the execution can disagree.

The verification checked all 11 intervals: the first starts at 0, each meets the preceding interval without a gap or overlap, and the last ends at 60. The unchanged function was also extracted into Godot to verify selection just before and exactly at each boundary. Including the start and end, 22 assertions passed. These checks cover both interval consistency and switching positions.

Using game rendering does not mean recording ordinary play

The capture node instantiates the real ChargeClicker. The script also changes progression state and invokes attacks at predetermined intervals.

Persistence is disabled, the language is English, and capture audio is muted. The footage uses the game's rendering, but it is not a person playing an ordinary run from beginning to end.

In V2, the game node is hidden for prime_art and final. Summing every other interval produced 51.5 seconds:

Interval category	Sum in the code
Game node visible	51.5 seconds
Cinematic image	3.5 seconds
Final title and destination	5.0 seconds
Total	60.0 seconds

This is a sum of scripted intervals. It is not a frame-by-frame review of the finished video measuring when the game is visible. If using the number in a production write-up, preserve how it was calculated.

Check the final file after combining music and video

The production README describes combining Godot's output with the selected music. It records choosing candidate A because its quiet/loud transitions aligned with the scene changes. This investigation did not listen to those candidates again.

The composition script scales video to 1920×1080 and outputs a 30 fps, 60-second MP4. Audio receives volume=0.63 and a 0.8-second fade beginning at 59.2 seconds.

The FFmpeg volume specification defines that value as an input multiplier. 0.63 corresponds to approximately -4 dB. It does not automatically normalize to a target loudness, so it is not a measured LUFS result for the final video.

The script also refuses to overwrite an existing output path. That supports comparing V2 while retaining V1. The composition script itself was not rerun during this investigation.

A configured 63 seconds and a file lasting 63.033333 seconds

The MP4 files were extracted from Git into temporary files and inspected with ffprobe 9.0.1:

Version	Resolution	Frame rate	format.duration
V1	1280×720	30/1	63.033333 seconds
V2	1920×1080	30/1	60.000000 seconds

Both contain H.264 video and stereo AAC audio at 48 kHz. V1's configured 63 seconds and its file duration are not identical. This metadata inspection alone does not locate the cause of that difference.

The README's timing table also rounds some times to whole seconds. When adjusting a caption or cut by frame, inspect the code's 4.5 seconds and the footage instead of relying on the descriptive “00:04.”

The reproduction script and recorded results preserve the intervals, file hashes, and ffprobe output. Neither source videos nor publication destinations were changed.

Use the interval table to decide the order of ideas and the finished file to verify the resulting order and duration. Keep the configured times alongside the durations verified in the output.

Audit a game soundtrack by selection records, playback slots, and actual files

hiro@ — Tue, 13 Oct 2026 04:08:13 +0000

Soundtrack candidates, selected compositions, stored files, and playback assignments gradually diverge. Replacing map music can leave the old file in storage, while two scenes may share one recording. “There are 18 tracks” does not explain what was counted.

Comparing VOLT NOMAD's production notes with its code found 18 BGM slots referring to 17 distinct audio files. Including the victory jingle makes 18 referenced files. The audio directory contains 19.

This article follows selection records through to playback assignments. The source is game-jam-lab at f074703, inspected on September 11, 2026. No listening comparison or music regeneration was performed.

Separate selection reasons from implemented assignments

The music production brief records purpose, title, Suno song ID, the selected A/B candidate, and the game file.

The enemy-specific expansion notes say that some initial candidates were too short and were removed from consideration. Tracks were regenerated with a specified duration, followed by another attempt for candidates that still ended early. The records identify an initial Relay Hydra A at 1:54 and Grid Leech A at 2:34.

Those durations are historical production records. This investigation did not retrieve and measure every Suno candidate again. They support the narrower observation that duration was a selection criterion at that stage.

The history also progresses from candidate records in 5ab837b to enemy-specific music in 290d302. That helps distinguish stored candidates from music that reached the implementation.

Follow the name to the playback key

The game's music code contains two dictionaries with different roles.

EncounterBGMKeys maps encounter or form IDs to BGM keys. BGMStreams maps those keys to audio files. A few inspected relationships are:

Encounter ID	BGM key	Referenced file
gearmaw	hunt	piston_hunt_loop.ogg
vaultback	vaultback	blue_vault_pulse.ogg
phase_mantis	phase_mantis	critical_parallax.ogg
prime_current_form_1	prime_current_form_1	prime_current_crownless_protocol.mp3

Following both stages avoids mistaking a differently named key for an unused composition. Gearmaw's dedicated track uses the generic key hunt.

desired_bgm_key() makes the actual selection. The open title or gallery, ordinary or boss combat, and the final boss form affect its result. A dictionary entry alone does not establish that the intended scene can reach it. The selection branches were inspected too, but every scene was not played through during this investigation.

18 slots, 17 BGM files, 18 files with the jingle

The automated count of dictionaries and Git-tracked audio produced:

Counted object	Count
Keys in `BGMStreams`	18
Distinct audio files referenced by those keys	17
Referenced files including the separate victory jingle	18
Stored files in the target audio directory	19

Both singularity and ending_world use arch_singularity.ogg. Separate scene slots do not create two compositions.

The previous map track, subterranean_hunt.ogg, remains stored but is absent from the inspected BGM dictionary's references. The current map key points to six_core_descent.mp3. This reflects retaining an earlier track after replacement; the investigation did not delete the unreferenced file.

The production brief's “18 tracks” corresponds to distinct BGM files plus the victory jingle. Keeping separate counts for keys, files, and stored material helps detect duplicates and omissions during cleanup or a port.

Compare measured file duration with rounded production notes

ffprobe inspected 19 audio files extracted from Git. Every audio stream was 48 kHz with 2 channels. Selected file durations were:

File	ffprobe duration in seconds
blue_vault_pulse.ogg	180.040000
cascade_trinity.ogg	179.880000
critical_parallax.ogg	179.800000
nomad_victory_signal.mp3	12.973500

“3:00” and “0:13” in the production table are rounded descriptions. They are not precise loop points or stop times. The values above are also file durations reported by ffprobe, not listening measurements of the first and last audible sounds.

The brief records mastering the initial tracks to approximately -18 LUFS. However, the original WAV files are not in this repository. This investigation neither reproduced that mastering pass nor established that every current track has equal loudness. Later MP3 additions were not assumed to have received the same processing.

Record loop configuration separately from listening approval

The implementation enables looping for Ogg and MP3 when switching BGM:

if next_stream is AudioStreamOggVorbis:
    (next_stream as AudioStreamOggVorbis).loop = true
elif next_stream is AudioStreamMP3:
    (next_stream as AudioStreamMP3).loop = true

Godot's AudioStreamMP3 reference documents its loop property. The code requests repetition, but musical continuity between the end and the beginning is a separate question. This investigation did not listen for seam noise, silence, or beat misalignment.

Two AudioStreamPlayer instances handle scene changes with a configured crossfade of 0.85 seconds. The short victory jingle has a separate player and does not enter the full-track BGM loop. These observations describe playback code, not measured listening comfort or mix quality.

Keep enough evidence for the next replacement

The verification script reads dictionaries and audio from the fixed commit and records reference existence, counts, SHA-256 hashes, and ffprobe data. The saved results used ffprobe 9.0.1. No audio conversion or upload took place.

For the next replacement, the same record can hold the candidate ID, selection reason, game key, file, and the extent of listening verification. The record then identifies the playback destination and any checks still pending.

Define one input action per screen across mouse, touch, and gamepad controls

hiro@ — Mon, 12 Oct 2026 02:52:55 +0000

Pushing a stick right should move the selection once. Treat every event received while the stick remains tilted as “next,” and the selection keeps jumping. Charging an attack, meanwhile, needs both the press and the release.

Supporting several input devices requires defining what counts as one action on each screen. This investigation read a fixed version of VOLT NOMAD and tested its gamepad direction conversion and button remapping in Godot.

The source is game-jam-lab at f074703. Verification took place locally on September 11, 2026; it was not a playtest across every supported device.

Do not invent an implementation sequence from the finished feature list

The history records shared gamepad settings in ef5cb81 on August 1, 2026, and the Project Charge prototype in b3be93e on August 2. Combat, gear trees, dialogue, and gallery screens subsequently grew around that code.

This does not support a linear story of finishing mouse support, then touch, then gamepad support. The implementation inherited shared input settings and added handlers as screens appeared.

The input code at the inspected revision first selects the open screen, dispatches to its handler, and returns. An action closing dialogue should not continue into the combat handling later in the same function.

Select the screen before interpreting the input

At its entry, _unhandled_input() calls set_input_as_handled(). It then routes events to dialogue, settings, the title, the gear tree, and other screens.

Marking an event handled in the Viewport and stopping execution inside the current function are separate jobs. The former does not automatically return from that function; the branch's return matters too. Godot's InputEvent documentation explains event delivery and the handled flag.

Events reaching ordinary combat follow these paths:

Input	Handling in the implementation
Left mouse button	Check position on press; end charging on release
Touch	Pass the press position to the same operations; end charging on release
Keyboard	Send events without echo to a dedicated handler
Gamepad button	Send events to a dedicated handler
Left stick	Convert motion into a single direction action before moving selection

These paths were inspected in source. This run did not test browser-generated mouse events from touch or multiple simultaneous fingers. Having both mouse and touch branches does not establish an absence of duplicate input on every device.

Wait for neutral before emitting another direction

This is the direction-selection function. It was extracted unchanged from the game and executed in a small class containing only the required controller_axis_latch state.

func controller_motion_direction(event: InputEventJoypadMotion) -> Vector2i:
    var direction := Vector2i.ZERO
    if event.axis == JOY_AXIS_LEFT_X:
        if absf(event.axis_value) < 0.45:
            controller_axis_latch.x = 0
        elif controller_axis_latch.x == 0:
            controller_axis_latch.x = 1 if event.axis_value > 0.0 else -1
            direction.x = controller_axis_latch.x
    elif event.axis == JOY_AXIS_LEFT_Y:
        if absf(event.axis_value) < 0.45:
            controller_axis_latch.y = 0
        elif controller_axis_latch.y == 0:
            controller_axis_latch.y = 1 if event.axis_value > 0.0 else -1
            direction.y = controller_axis_latch.y
    return direction

Returning below an absolute axis value of 0.45 clears the latch. Otherwise, the function emits a direction only when the stick first leaves the unlatched state.

Synthetic horizontal-axis events produced this sequence:

Axis value	Returned direction	Meaning
0.2	None	Within the neutral region
0.7	Right	First action
0.8	None	Still tilted
-0.8	None	No neutral event has arrived
0.1	None	Latch cleared
-0.8	Left	Next action

Even jumping directly from a positive to a negative value does not emit the opposite direction without a neutral event. This function has no timed repeat while held. Changing that behavior to suit physical controls requires a different rule for repeated input.

The full check covered 10 events, including the vertical axis independently emitting an action while the horizontal axis remained latched.

Remapping must preserve other input types

The shared controller settings class swaps assignments when a new button is already assigned to another action. That avoids binding two actions to the same button.

When updating InputMap, it removes only InputEventJoypadButton events. It does not clear keyboard events assigned to the same action.

Tests against the actual class verified that:

Moving primary to secondary's existing button moves secondary to primary's previous button.
Unsupported buttons and unknown action IDs are rejected without changing the bindings.
Changing attack's gamepad button preserves a previously assigned Space key.

These checks cover the shared class. They do not prove that every key assignment automatically reaches every VOLT NOMAD screen. The game also performs its own button checks, so each screen's route needs inspection.

Record the scope of support precisely

The runtime was Godot 4.6.2.stable.official.71f334935 in headless mode. The test did not read the game's saved progress, and writing controller settings was disabled. The reproduction script and input results are recorded.

This run verified conversion and remapping after synthetic events arrived. Browser focus, event generation from touch, controller connection and disconnection, button labels, and comfort during extended play require separate checks.

An input support checklist should record the screen, the meaning of press, release, and continued input, and the sequence actually tested. Record code-level checks separately from actions a person has verified on a device.

An outbox preserves notification intent; delivery deduplication is a separate boundary

hiro@ — Wed, 07 Oct 2026 01:39:03 +0000

Saving a record before calling a notification API leaves a gap where execution can stop. The data exists, but there is no record that a notification was required. Reversing the order can notify someone about data that never saved successfully.

The outbox pattern saves business data and an event to deliver later in the same database transaction. That does not, by itself, make external delivery happen once.

This experiment put note creation and outbox insertion into one local D1 batch, then tested a consumer stopping after successful transmission. It ran on September 11, 2026, with a fake external provider. No actual notifications or production changes were made.

Persist notification intent first

AWS's transactional outbox guidance addresses inconsistencies between database updates and message delivery. Business data and the event are stored in one transaction and delivered afterward. Duplicate delivery still needs handling.

The experiment placed a note table and this outbox table in the same D1 database:

CREATE TABLE outbox (
  event_id TEXT PRIMARY KEY,
  note_id TEXT NOT NULL,
  kind TEXT NOT NULL CHECK(kind = 'note.created'),
  payload TEXT NOT NULL,
  sent INTEGER NOT NULL DEFAULT 0
);

event_id identifies the persisted event rather than being regenerated for every delivery attempt. The JSON payload contains the note ID and its title at that point. Retries do not reread the current note, so the same event retains its contents.

One batch receives the two inserts:

await db.batch([
  db.prepare('INSERT INTO note VALUES (?, ?, ?)')
    .bind(id, 'actor-a', 'hello'),
  db.prepare('INSERT INTO outbox(event_id,note_id,kind,payload) VALUES (?, ?, ?, ?)')
    .bind('event-'+id, id, kind, payload),
]);

This is an excerpt from the verification code. The transaction provided by D1's batch API covers those database writes. Sending to an external service does not participate in it.

Does a failed event insert leave the note behind?

The outbox CHECK constraint permits only note.created. Passing an invalid kind forced the second INSERT to fail.

The result was 0 notes and 0 outbox events. The earlier note insertion was rolled back too.

A valid creation produced 1 note and 1 outbox event before the consumer ran. Calling the consumer afterward delivered 1 event to the fake provider. This verified that delivery can start separately from business creation using the event stored in the database.

That differs from merely deferring a notification Promise: the input required to resume delivery exists as a database record. However, this local experiment disabled persistence. It did not restart an actual process or host to test storage durability.

Successful transmission can still precede a missing sent record

The experimental consumer follows this order:

Read one unsent event
Pass event_id and payload to the provider
Wait for successful transmission
Update outbox.sent to 1

If the consumer stops before that final update, the provider has processed the event while the outbox still marks it unsent.

The test threw immediately after the fake provider returned success. Calling the consumer again against the same database transmitted that event again. It simulated interruption between transmission and recording with an exception rather than forcibly terminating a process.

Without provider deduplication, there were 2 calls and 2 operations counted as deliveries. The outbox's sent flag alone did not prevent the duplicate in this interval.

Setting sent to 1 before transmission would create the opposite problem: a failed send could disappear from the retry set. Reordering one flag cannot atomically align the provider's result with the database's result.

A receiver that recognizes the event can consolidate retries

The next case used a fake provider that treated the same event_id and payload as an existing result. The test would fail if an identical ID arrived with different contents.

After the same interruption and retry, the provider received 2 calls but counted only 1 delivery:

Condition	Database or provider result
Constraint failure on outbox INSERT	0 notes, 0 events
Commit succeeds before consumer starts	1 note, 1 event, 1 delivery
Interruption after send, no provider deduplication	2 calls, 2 deliveries
Same interruption, provider deduplicates by event_id	2 calls, 1 delivery

After retry, sent was 1. A further consumer call also confirmed that no unsent event remained.

The provider is a fake running inside Node.js. Its deduplication records never expire, and it does not represent the guarantee of an actual notification service. A real integration must verify which key the receiver remembers, for how long, and within which scope.

If the receiver cannot make the effect happen once, design the consuming experience for possible duplicates. Introducing an outbox is insufficient evidence for exactly-once delivery.

Separate the single-consumer experiment from operational requirements

The environment was Node.js v24.15.0, Wrangler 4.81.1, and Miniflare 4.20260409.0. Remote D1 bindings were disabled, with synthetic data and the fake provider used throughout.

The implementation calls one consumer sequentially. It has no claim or lease preventing multiple workers from selecting the same unsent row, no retry schedule, no failure limit, and no dead-letter queue. These tests do not justify scaling it directly to multiple consumers.

In operation, expose the pending-event count, longest waiting time, and failure reasons. If the provider stops, preserve events for retries and investigation. When changing the payload schema, also check whether the new consumer can still read old pending events.

This experiment verified atomic storage of business data and delivery intent, retrieval before delivery, and redelivery after interruption between sending and recording. An outbox closes the gap in which business data changes while notification intent is lost. Preventing duplicates beyond that boundary also requires a design for the receiver of the same event.

An idempotency key needs stored results: testing retries and concurrent requests

hiro@ — Tue, 06 Oct 2026 03:28:58 +0000

When a create request produces no response, the client cannot distinguish failure before creation from a committed creation whose response was lost. Retrying can create a second record.

An idempotency key connects that retry to the same logical request. Preventing duplication also requires deciding how the server stores the key, input, and result.

This experiment put note creation and result storage into one local D1 batch(), then checked lost responses, concurrency, mismatched inputs, and deleted records. The investigation ran on September 11, 2026. It is a demonstration implementation, not a rollout to an existing application.

Define what the same key identifies

Stripe's idempotent-request documentation describes saving the first request's status code and body and returning that result for the same key. It also compares inputs and treats reuse after the record is removed as a new request.

That behavior requires more than a header name. It is also Stripe's contract: adding the same header name to a custom API does not automatically implement storage or comparison.

The experiment defined key scope using three components:

Authenticated actor / operation and version / client key
actor-a / create-note:v1 / key-a

Another actor can use key-a for a separate creation. The same actor retrying the same operation returns to the original input and result. The actor is a trusted argument to the experimental function; HTTP authentication was not implemented.

Store an input fingerprint and the response result

The result table was:

CREATE TABLE request_result (
  actor TEXT NOT NULL,
  operation TEXT NOT NULL,
  request_key TEXT NOT NULL,
  fingerprint TEXT NOT NULL,
  status_code INTEGER NOT NULL,
  body TEXT NOT NULL,
  PRIMARY KEY(actor, operation, request_key)
);

The fingerprint is the SHA-256 of JSON containing the single experimental input, title. This is not a general normalization algorithm for arbitrary JSON. A real API must include every input that affects the operation.

If the key already exists, the function compares fingerprints and returns the stored result when they match. A mismatch produces an error carrying status 409 in this implementation. That is a demonstration-specific choice, not an attempt to reproduce Stripe's error contract.

For a new key, the function generates a note ID and stores both the note and the response containing that ID:

await db.batch([
  db.prepare('INSERT INTO request_result VALUES (?, ?, ?, ?, ?, ?)')
    .bind(actor, operation, key, fingerprint, 201, JSON.stringify(body)),
  db.prepare('INSERT INTO note VALUES (?, ?, ?)')
    .bind(body.id, actor, title),
]);

body contains the generated ID and title. The surrounding experiment code also implements lookup, replay, and rereading after a write conflict.

The D1 batch contract provides the transaction boundary for the two writes. This avoids preserving a successful response when creation of its note failed.

An existence check alone does not handle concurrency

Two requests can both read that no key exists. The test introduced a barrier to force that situation:

Request A: observes no key ─┐
                           ├─ Wait until both reads finish
Request B: observes no key ─┘

Then both execute their batches

The inserts compete for the same composite primary key. Only one batch succeeds as a new creation; the other rereads the saved result and compares the fingerprint before returning it.

Assertions verified that both initial lookups missed, only 1 note existed, and both calls returned the same body. The test did not infer concurrency safety merely from a run where one request happened to finish first.

The initial SELECT can provide a fast replay path. The unique constraint and atomic writes prevent duplicate creation at the final boundary. An in-process Map alone would not cover requests handled by another process.

Return to the same ID after losing a response

The test threw an exception after creation committed to simulate a caller missing the success result. It did not interrupt actual HTTP traffic.

Calling the function again with the same actor, key, and title returned the original body and status value 201, while the note count remained 1. Storing the result, rather than only a completion marker, lets the retried caller learn the same ID.

The full set of cases was:

Condition	Result
Response lost after commit, followed by identical retry	Same body and 201; 1 note
Same actor and key, changed title	Rejected with 409; still 1 note
Another actor uses the same key	Separate note; 2 total
Both concurrent requests observe no key	1 note, identical bodies, 1 creation and 1 replay
Note creation violates a CHECK constraint	0 notes and 0 saved results
Saved result deleted before an identical retry	New note; 2 total

The last case explicitly deleted the record to simulate the end of retention. Automatic TTL deletion was not implemented. If keys are not remembered forever, clients need to know what happens when the same request arrives after retention ends.

This implementation caches only successful creation

The environment was Node.js v24.15.0, Wrangler 4.81.1, and Miniflare 4.20260409.0. Remote bindings were disabled; only local D1 and synthetic data were used.

The implementation atomically saves the note and its successful result. It does not reproduce a contract such as Stripe's that also retains failure results after execution begins. Authentication, input validation, replay of HTTP headers and the complete response, and retention operations require separate work.

The batch also contains only D1 writes. This mechanism alone cannot make an external notification or file transfer happen once. An external operation needs its own defined key and result-reuse behavior.

If duplicate business data must remain impossible after request records expire, enforce that condition in the business table too. The time window for deduplicating retries need not match the lifetime of a business uniqueness rule.

Review scope, input matching, concurrent creation, result replay, and post-deletion behavior alongside the presence of a key. Use those results to describe which duplicate operations the API prevents.

Choosing Cron Triggers, Queues, or Workflows by where recovery should resume

hiro@ — Mon, 05 Oct 2026 02:35:15 +0000

A daily report, a call to an external API, and a process waiting for approval are all background work. Combining them under one mechanism can obscure what should be repeated after failure.

Cron Triggers handle when work starts, Queues handle messages being delivered, and Workflows handle stages of a process with intermediate state. Choose by the unit of recovery as well as execution duration.

Official documentation was checked on September 11, 2026. The reporting and approval flow below is a design example. No production triggers, queues, or workflows were created.

Describe the unit of retry in one sentence

Consider a daily participation report for several organizations. Separate the initial requirement from later additions:

Requirement	Desired recovery unit	Mechanism to consider
Start a short report every morning	The report for that day	Cron Triggers
Process organizations independently and retry only some	A message identifying the organization and reporting date	Queues
Wait for review after reporting, then continue if approved	The unfinished step of the overall process	Workflows

These are not mutually exclusive choices. A time trigger can start message delivery, with only the jobs that need it entering a multi-stage process.

All three are not necessarily needed from the beginning. A short one-shot report requires different state from a process with per-organization delivery and approval waits.

Cron Triggers take responsibility for when work starts

The Cron Triggers documentation describes invoking a Worker's scheduled handler using cron expressions, with times interpreted in UTC.

For a daily report, decide the reporting date separately from the start time. If execution crosses a date boundary or a previous day's job is repeated, the intended reporting period should not change accidentally.

The design could use a business job identifier like:

daily-summary / organization-red / 2026-09-11

This is a business identity example, not a trigger configuration. Decide whether rerunning the same date is the same job or a revised report with a new version.

Installing a Cron Trigger does not itself represent “red finished, blue remains incomplete.” If a short batch remains sufficient, store those outcomes in a database or another record and define which portions can be repeated.

Queues define which message receives a retry

When organizations should be processed independently, a message can become the delivery unit. Attach the needed parameters to the identity above.

Queues' delivery guarantee is at-least-once. A message may arrive more than once, so received-message counts and business-operation counts are different.

The ack and retry documentation describes acknowledging individual messages so that an ensuing batch failure does not redeliver those already acknowledged. Individual retry requests redelivery for that message. A successful consumer return also provides automatic acknowledgement.

Suppose a batch contains jobs for red, blue, and green, but only blue encounters an external API failure:

red:   saved successfully → ack
blue:  temporary failure → retry
green: saved successfully → ack

The proposed handling records which jobs succeeded and returns the failed job for redelivery. However, if the API succeeded but its response was lost, a retry can still repeat an external side effect. Acknowledgement controls message delivery; it does not make the external operation happen exactly once.

Decide where jobs go after retries are exhausted. If using a dead-letter queue, assign responsibility for inspecting and redriving it. This investigation did not create or execute a consumer or DLQ.

Workflows represent completed stages and waiting

A process that waits for an administrator after generating a report needs more than a standalone message. It needs to represent completed work, the condition being awaited, and what will resume execution.

Workflows' sleep and retry documentation describes steps, retries, and waits. The event-waiting API also provides waitForEvent() for a specified event type.

A proposed flow could be:

Finalize the report for organization red and the reporting date
Save the result for review
Wait for an approval event
Validate the approval and continue
Record the outcome

Putting report generation, external transmission, and a subsequent save into one step broadens the work repeated when the later operation fails. Step boundaries determine retry boundaries.

The Rules of Workflows also call for idempotent API and binding operations because a step can run repeatedly. Moving code into a Workflow does not automatically deduplicate external sends.

An approval wait needs a deadline and an expiration policy. The end of a wait without approval must not be interpreted as approval. Authenticating the sender and checking that the event applies to the correct job remain application responsibilities.

Preserve business identity when combining the mechanisms

A possible architecture as requirements grow is:

Cron: choose the reporting date and start
  ↓
Queues: deliver each organization's job
  ↓
Workflows: handle jobs needing waits or multiple stages

A record that the daily trigger ran does not reveal whether a particular organization's job is still awaiting approval. Conversely, a completed Workflow does not establish that jobs were created for every organization expected that day.

Keep the reporting date, organization, and job ID connected, then compare the expected job set with completed jobs. Unconditionally creating new IDs on redelivery or restart makes duplicate business work harder to trace.

This architecture also adds delivery configuration, step state, and logs to investigate. Throughput and cost were not compared, so this article does not claim that combining the mechanisms improves efficiency.

Plan partial failures before testing the rollout

At an actual rollout, separately test at least an isolated organization failure, a lost response after a save, and an approval that never arrives. These are proposed checks for the target environment, not tests executed in this investigation.

They examine delivery granularity, idempotency, and waiting-state deadlines respectively. Reducing all of them to “the batch failed” loses the information needed to choose a restart point.

Start by defining the unit of work that can be repeated. A timed invocation may suffice; other work needs per-message redelivery or preserved progress while waiting for the next stage. Add components according to that distinction.

Inventory cross-room queries before moving D1 data into Durable Objects

hiro@ — Sun, 04 Oct 2026 03:01:29 +0000

When moving room state into Durable Objects, similar storage SQL does not mean every D1 query can move unchanged. Each Object has its own SQLite storage. Splitting data previously held in one D1 database also changes how you retrieve records across rooms.

This article tests that boundary. The experiment stored the same synthetic data in one local D1 database and two local Objects, then compared individual and cross-room reads. No live service was migrated. The migration steps later in the article are design proposals based on the experiment.

Start with a query the migration must preserve

Consider a small room system: alice belongs to red, and bob belongs to blue. One D1 database can store both in this table:

CREATE TABLE membership (
  room_id TEXT NOT NULL,
  user_id TEXT NOT NULL,
  PRIMARY KEY (room_id, user_id)
)

Besides listing members of a particular room, an administration screen can retrieve every membership with one query:

SELECT room_id, user_id FROM membership ORDER BY room_id, user_id

This full-table read is for comparison. A large administration screen needs pagination, and reading every row may be undesirable. The point here is that a query spanning room boundaries stays within one database.

The Durable Object Storage specification describes storage attached to an individual Object. It is not a shared database that automatically brings another Object's tables into this SELECT.

Create the same table in two Objects

The experimental Room class creates a member table during initialization and exposes RPC methods to add and retrieve members. Because the Object itself represents a room, this table has no room_id column.

import { DurableObject } from 'cloudflare:workers';

export class Room extends DurableObject {
  /** @param {DurableObjectState} ctx @param {Env} env */
  constructor(ctx, env) {
    super(ctx, env);
    ctx.blockConcurrencyWhile(async () => {
      ctx.storage.sql.exec('CREATE TABLE IF NOT EXISTS member (user_id TEXT PRIMARY KEY)');
    });
  }

  /** @param {string} userId */
  add(userId) {
    this.ctx.storage.sql.exec('INSERT INTO member (user_id) VALUES (?)', userId);
  }

  members() {
    return this.ctx.storage.sql.exec('SELECT user_id FROM member ORDER BY user_id').toArray();
  }
}

Env is generated from the Wrangler binding configuration. Here, blockConcurrencyWhile controls event delivery during initialization. This is not an example of putting a long external request inside that block; consult the State API documentation when choosing where to use it.

The caller obtains Objects by room name:

const red = env.ROOMS.getByName('room:red');
const blue = env.ROOMS.getByName('room:blue');
await red.add('alice');
await blue.add('bob');

Using the same name in the same namespace provides a way back to the same storage. The Namespace API distinguishes named lookup from generating a new unique ID. Calling newUniqueId() on every request does not look up an existing room.

What the local run returned

After completing the writes, the experiment performed the reads below. The harness passed 8 assertions, including the successful HTTP response.

Read	Returned data
`members()` on `room:red`	Only `alice`
`members()` on `room:blue`	Only `bob`
Retrieve again using the same name, `room:red`	Only `alice`
A separate Object created with `newUniqueId()`	Empty array
Global D1 query	`blue/bob` and `red/alice`
Explicitly fetch both rooms over RPC and combine	Matches the global D1 query
Fetch and combine with only `red` in the target list	Only `red/alice`

The application can still gather data after storage is split. This is the collection function used in the experiment:

/** @param {Env} env @param {string[]} roomIds */
async function collectMembers(env, roomIds) {
  const groups = await Promise.all(roomIds.map(async roomId => {
    const room = env.ROOMS.getByName(`room:${roomId}`);
    const members = await room.members();
    return members.map(member => ({ room_id: roomId, user_id: member.user_id }));
  }));
  return groups.flat().sort((a, b) => a.room_id.localeCompare(b.room_id));
}

The caller is responsible for the room list. Getting 1 record after passing ['red'] does not establish that only 1 record exists globally. This experiment used a fixed room list; it implements neither enumeration of all Objects nor persistent management of that list.

Waiting for each RPC and combining the arrays does not create a transaction that reads all Objects at the same instant. The results matched here with writes stopped. A consistent global snapshot under concurrent updates was not tested. If any RPC fails, this Promise.all also fails. Whether to return partial results or repeat the entire read is a separate decision based on the screen's requirements.

Decide where reads and writes will go before migrating

Based on this result, an investigation of a proposed migration can inventory existing queries as follows. The right column lists decisions to make, not features implemented in this experiment.

Existing operation	Question after partitioning storage by Object
Retrieve members of one room	Can the room ID consistently reach the same Object?
Search all rooms in an administration screen	Keep aggregate data elsewhere, or collect from a known target list?
Find every room a user has joined	Where will an index starting from the user live?
Make a change affecting multiple rooms	How will partial success be detected and recovered?

One possible design retains aggregate data in D1 for global search. That requires deciding which store owns updates, how much projection lag is acceptable, and what can rebuild missing updates. Sequential writes to D1 and an Object do not make the two stores one transaction. Writing the same data twice in this experiment prepared the comparison; it did not implement a synchronization mechanism.

Another option keeps data in D1 and uses Objects to coordinate communication or operations for a room. Conversely, storing data inside the Object can be useful when state should stay within the room boundary. Apply the combination of execution context and storage described in the Durable Objects overview to the unit of work in your application.

Inventory read and write paths to identify which cross-room operations must change, even though both stores use SQLite.

Environment and reproduction

The experiment ran on September 11, 2026, with Node.js v24.15.0, Wrangler 4.131.0, and its Miniflare dependency, 5.20260910.0-alpha. The Worker's compatibility date was 2026-09-11. The package's convertV4MiniflareOptions converted the older option format. Wrangler generated the types, and checkJs passed with @cloudflare/workers-types 5.20260911.1 and TypeScript 5.9.3.

The local experiment script has its Worker and configuration in the adjacent do-partitions/ directory. The recorded output is also available.

To reproduce it, install the specified Wrangler version in a separate scratch directory and pass the path to its node_modules/wrangler/package.json as the script argument. It does not connect to remote D1 databases or Objects. Storage is temporary, and the runtime is disposed at the end.

Performance, pricing, WebSockets, recovery across failures, and production data migration are outside this experiment. The results show the scope of reads after partitioning storage by Object and the application work needed for a global read.

Replacing deep OFFSET pagination in D1: rows read and inserts between pages

hiro@ — Sat, 03 Oct 2026 02:30:51 +0000

LIMIT 20 OFFSET ... makes the next page of a list easy to express. But deeper pages require skipping more rows without returning them. Using an index does not, by itself, eliminate that work.

This experiment inserted 100,000 synthetic notifications into local D1 and fetched the same 20 records with OFFSET and a cursor. It examined how many rows were read and what happened when a new row arrived between pages.

The checks ran on September 11, 2026. They do not measure production D1 latency or billing, or establish a universal row count at which pagination becomes slow.

Define a key that preserves the same order

The experimental schema was:

CREATE TABLE notification (
  id INTEGER PRIMARY KEY,
  user_id TEXT NOT NULL,
  created_at INTEGER NOT NULL
);
CREATE INDEX idx_feed
  ON notification(user_id, created_at DESC, id DESC);

It contained 100000 rows for user-a, with created_at set to the integer part of the ID divided by 3. Multiple records therefore shared a timestamp.

The order was created_at DESC, id DESC. Timestamp alone cannot uniquely order tied rows, so the ID belongs in both the ordering and the cursor. This example assumes non-null ordering columns and a unique ID.

SQLite's Row Values documentation describes comparing multiple columns together and applying that technique to scrolling lists. This experiment checked it in D1 SELECT statements.

Retrieve the same 20 records with both methods

The OFFSET query skips a specified number of records from the beginning:

SELECT id, created_at
FROM notification
WHERE user_id = ?
ORDER BY created_at DESC, id DESC
LIMIT 20 OFFSET ?;

The cursor query searches after the last record of the previous page. Because the order is descending, the comparison uses <:

SELECT id, created_at
FROM notification
WHERE user_id = ?
  AND (created_at, id) < (?, ?)
ORDER BY created_at DESC, id DESC
LIMIT 20;

The cursor values are the previous page's final created_at and id. Using only created_at < ? could skip remaining rows sharing the boundary timestamp.

The measured positions were offsets 20, 1000, 10000, 50000, and 99000. For each comparison, the immediately preceding row was retrieved in advance. Finding that cursor was excluded from the measurement. A real “Next” action carries those values from the previous result; jumping directly to an arbitrary page number is a different operation.

Rows read differ substantially from rows returned

At every position, the ID-and-timestamp arrays matched and contained 20 records. The final measured query's meta.rows_read values were:

OFFSET position	Rows read with OFFSET	Rows read with cursor
20	40	23
1000	1020	22
10000	10020	22
50000	50020	23
99000	99020	21

The cursor did not always read exactly 20 rows; it read 21 to 23 in this dataset. OFFSET's reads increased with the position.

EXPLAIN QUERY PLAN showed both queries using the same covering index. The relevant output was:

OFFSET:
SEARCH notification USING COVERING INDEX idx_feed (user_id=?)

Cursor:
SEARCH notification USING COVERING INDEX idx_feed (user_id=? AND created_at<?)

Check which condition defines the search starting point as well as whether an index is used. Equality of the returned arrays also verified that the comparison including id produced the intended results.

The D1 index documentation distinguishes returned rows from read rows and describes inspection using EXPLAIN QUERY PLAN and meta.rows_read. These numbers came from local Miniflare; they are not production-billing measurements.

Timing does not establish one universal cutoff

The environment was macOS/arm64 on an Apple M4 Max, Node.js v24.15.0, Wrangler 4.81.1, and Miniflare 4.20260409.0. The configuration specified compatibility date 2026-09-11, but this version of getPlatformProxy does not pass that date to the Worker it creates. The measurements cover this local D1 implementation, not Worker behavior for the requested date. Remote bindings were disabled and local D1 persistence was off.

Each position had 4 warmup rounds followed by 11 measured rounds. Query order alternated between OFFSET and cursor. performance.now() measured the wait for .all(), including local proxy overhead but excluding cursor preparation and result assertions.

OFFSET position	OFFSET median ms	Cursor median ms
20	1.435	1.219
1000	1.113	0.990
10000	1.026	1.084
50000	1.809	1.123
99000	2.971	1.137

At shallow positions, call-to-call variation matters; the medians even reversed at 10000. The cursor at the first position had a maximum observation of 9.911 ms. This table does not justify a universal rule such as switching at 10000 records.

The clearer finding is that deeper OFFSET queries read more rows, with timing differences also appearing at the deeper positions in this run. A production decision needs measurements against the real distribution, page size, query frequency, and response-time target.

Inserting between pages produces an OFFSET overlap

The test also fetched the first 20 records, then inserted 1 new row ahead of them.

The first page ended at ID 99981. Fetching the next page with OFFSET 20 after the insertion returned 99981 again as its first row. The new leading record pushed the previous twentieth record into the twenty-first position.

Using the saved cursor instead returned 99980 first, with no IDs overlapping the previous page. Assertions checked that result too.

A cursor is not a snapshot of the entire list, however. Updating ordering values between requests, or reproducing the same list including deleted records, needs additional rules. The mutation test here covered only 1 insertion at the beginning.

Start with lists that need a Next action

Cursor pagination receives its next position from the preceding page. An interface that jumps directly to a page number must locate that position separately. Excluding cursor preparation from this experiment's timing makes that distinction explicit.

The reproduction code includes data creation, result equality, query plans, measurements, and the insertion test. Alongside index usage, check that the methods return the same records and how much each reads to reach the next page.

Debugging mixed ESM and CommonJS: separate module classification from loading

hiro@ — Fri, 02 Oct 2026 02:44:50 +0000

You see require is not defined, replace it with an import, and then encounter a syntax error in another file. When ESM and CommonJS coexist, changing syntax alone can make the original cause difficult to follow.

First ask how Node.js classifies the file. Then ask how that file loads another module. Separating these questions helps determine whether to change package.json, a filename extension, or the asynchronous boundary of the caller.

This investigation ran 10 small-file cases in separate processes on Node.js v24.15.0. It used no bundler, TypeScript transformation, or custom loader, and removed NODE_OPTIONS from child processes. Official documentation was checked on September 11, 2026; the latest pages displayed v26.8.2. The experimental results are specifically for v24.15.0.

Check the extension and nearest package.json first

The official Packages documentation identifies .mjs as ESM and .cjs as CommonJS. For .js, the nearest parent package.json can explicitly select the system through type.

“Nearest” matters: inspecting only the repository root can miss the applicable setting. The experiment placed a child directory with type: commonjs inside one configured with type: module.

esm/
  package.json            type: module
  require.js
  legacy.cjs
  nested/
    package.json          type: commonjs
    legacy.js

Calling require() inside require.js failed. In both legacy.cjs and nested/legacy.js, however, typeof require produced function. The extension or the inner configuration can select CommonJS even inside an outer ESM package area.

The reverse was checked too. A static export in a .js file under type: commonjs produced a syntax error, while an .mjs file in the same area executed successfully.

An untyped js file is not necessarily CommonJS

Assuming that omitting type always preserves the old CommonJS behavior is incomplete for current Node.js. The documentation describes syntax detection: input without an explicit classification can be treated as ESM when it contains ESM-only syntax.

The experiment ran this .js file in a directory containing an empty package.json:

export const value = 42;
console.log(value);

It printed 42 and emitted a MODULE_TYPELESS_PACKAGE_JSON warning. The same export failed with an explicit type: commonjs, but succeeded through syntax detection when type was absent.

Adding type: module simply to remove that warning also affects existing .js files governed by the same setting. First identify the target file and the files sharing that configuration. For a localized migration, .mjs and .cjs can make the intention explicit.

The performance cost of syntax detection was not measured. This experiment checked execution outcomes and the warning.

require can load some ES modules

The older rule “CommonJS must always use import() to load ESM” also needs qualification. The CommonJS documentation for the tested version describes the conditions under which require() can load synchronous ESM.

The target ES module contained:

export const value = 42;

The CommonJS caller read the named export from the returned object:

console.log(require("../esm/sync.mjs").value);

It printed 42. An .mjs extension alone does not establish that require() must reject the module.

Changing the target to this made require() fail with ERR_REQUIRE_ASYNC_MODULE in the same environment:

await Promise.resolve();
export const value = 42;

The difference is top-level await. The documentation also excludes synchronous loading when top-level await occurs elsewhere in the imported module graph. The experiment placed it directly in the target module.

Dynamic import does not turn its caller into ESM

The CommonJS file then loaded the asynchronous ES module like this:

import("../esm/async.mjs").then(m => console.log(typeof require, m.value));

The output was function 42. It waited for the ES module and obtained its value, while require remained available in the caller. Adding an import() expression did not switch the entire CommonJS file into ESM.

However, replacing a synchronous load with import() means waiting for its result. The caller may also need an asynchronous interface. Distinguish a configuration problem from a change that requires an asynchronous boundary.

Correct classification does not guarantee correct path resolution

An ESM relative import of ./sync failed with ERR_MODULE_NOT_FOUND even though sync.mjs was next to it. The ESM documentation requires extensions for relative and absolute import specifiers.

That is separate from whether the target is ESM or CommonJS. This example needs ./sync.mjs. A shorthand accepted by a bundler need not work when passed directly to Node.js.

The 10 checked cases were:

Condition	Result
require in a `.js` file under `type: module`	`require is not defined`
Static export in `.js` under `type: commonjs`	Syntax error
`.cjs` under `type: module`	Runs as CommonJS
`.mjs` under `type: commonjs`	Runs as ESM
`.js` beneath an inner `type: commonjs` package	Uses the inner setting
CommonJS requires synchronous ESM	Retrieves the value
CommonJS requires ESM with top-level await	`ERR_REQUIRE_ASYNC_MODULE`
CommonJS dynamically imports that ESM	Retrieves the value; require remains available
An ESM relative import omits the extension	`ERR_MODULE_NOT_FOUND`
A `.js` file with no type contains export	Runs through syntax detection, with a warning

The reproduction script creates a temporary directory, asserts exit codes and output for every case, then removes it. It does not change an existing project's package.json.

Conditional package exports, CommonJS named-export detection, and TypeScript configuration are outside this experiment. For an initial investigation of mixed-module errors, check the Node.js version, file classification, loading method, and relative path in that order.