Handoff: Rebase legacy migration after tail recovery and run its final local suite

Written 2026-10-19 21:34 UTC.

RE-VERIFY: This is a write-time snapshot. Recheck https://github.com/CodexCoder21Organization/SearchableBucketEmbedded/pull/14 and https://github.com/CodexCoder21Organization/SearchableBucketEmbedded/pull/15 with gh pr view <full-url> --json state,headRefOid,mergedAt, then fetch their current refs. No CI status was checked here: the brief assigns CI to the orchestrator.

Design decisions in force

On 2026-10-19 the original owner request was: “We need to investigate why https://my.externalbrain.wasmserver.com/ is failing to load and fix the underlying problem.”

Owner requirement quoted by the task: “startup (and incremental recovery) should always be fast. If there is any situation where startup or incremental recovery are slow, that's a bug which should have been tested and exercised by https://github.com/CodexCoder21Organization/DocumentationRepository/blob/main/architecture/TESTING.md#extreme-condition-testing-load-fuzzing-failure-injection-and-chaos and which should be fixed.”

The round-two brief requires: “No merging, enqueueing, deploying, or touching production. Publish nothing unless this brief grants it by name.” It requires version 0.0.14, the companion tail-recovery PR to merge first, then rebase onto main, one full local suite from the exact final pushed head, and stop at the open PR. “Never raise a timeout, heap size or start budget, and never reduce an iteration count.” “Do not watch CI; the orchestrator does that.” These rules continue to apply. The separate bucket-metadata heap finding belongs to another lane; do not take it over here.

Mission and remaining work

Finish the final integration and validation of https://github.com/CodexCoder21Organization/SearchableBucketEmbedded/pull/15 after its required companion https://github.com/CodexCoder21Organization/SearchableBucketEmbedded/pull/14 merges. The round-two changes are pushed, all eighteen new/strengthened scenarios have focused failure/pass evidence, and independent test/code reviews have completed. The one full local suite has NOT run. The prepared ownership-aware integration is saved remotely as text/patches, not yet applied to the PR branch because the companion is still open.

Production facts below come from the supplied brief, not a fresh production inspection by this lane: embedded 0.0.5 rebuilt and replayed the index before binding the listener, while ContainerNursery stopped startup before completion. Production contained both events.json and events.jsonl. No deploy, publication, production access, PR merge, or enqueue was performed by this lane.

What was found and done

1. Legacy JSON syntax, missing-field and unknown-type errors escaped without a global record range/path. The production fix catches JSONException around only the legacy object parse and throws IllegalStateException with path, UTF-8 [start,end) and original cause. The callback remains after the catch. Three full-message tests follow an earlier Unicode record; another verifies callback exception identity. Failing parser tests were the first pushed milestone.
2. Strengthened the existing byte observer to count source, openReadOnly and openReadWrite reads without double counting. The old observer passes a source-prefix-scan mutation; the new observer rejects it. Both retain existing 15,001-record workload and budgets.
3. Added four interrupted resumes on one history at records100/250/450/650, checking every durable snapshot, minimum read offset/bytes, monotonic saved progress, final401 remaining events and next-open0. It rejects suppressed resumed checkpoints and prefix scanning. Separate skip-event mutations prove the important replacement/removal operations remain visible in snapshots.
4. Added a 32 MiB boundary history with replacements/removals before/at/after the boundary and a separate scratch bucket delete/recreate lifecycle. Skip31/32/33 mutations fail at the intended state assertions; no later deletion masks them.
5. Added six deterministic child stops: before first commit, legacy source close, JSONL handover, during JSONL, before final publication, after final publication. Added final-checkpoint write exhaustion using child prlimit --fsize=65536:65536 and a long final event id. It asserts the full IOException File too large plus commit-write stack, previous atomic snapshot, exact suffix recovery and clean reopen. Mutations that discard cursors, leave legacy incomplete, skip events or omit final commit are red.
6. Tiny shape streams1,000,000 short records under128MiB, checking full ordered ids/timestamps/type/bucket/count. A retention mutation fails with Java heap space. Large shape checks a >2 MiB escaped Unicode body exactly through manager recovery; a record-cap mutation is red.
7. Old asynchronous filesystem notification/SIGSTOP windows were replaced with owned read barriers. Important Okio detail: FileHandle.read fills its requested buffer by repeated protectedRead calls. At a non8192-aligned stop, return EOF ONCE so a short fill reaches the parser; on the next request at that same byte, park/halt/throw. Halting on the first protectedRead boundary can prevent the last record callback and tests the injector rather than the checkpoint. This was diagnosed and corrected in draft tests; those failed drafts are not claimed as production failures or mutation proof.
8. Independent coverage review found two masking gaps (replacement later deleted, and operations hidden before the first stop). Both were fixed and separately mutation-proven. Independent code review narrowed README wording to legacy JSON syntax/event validation and legacy callbacks; pre-existing JSONL catch scope was preserved.
9. Companion revisions now add EventLog Closeable/native FileChannel ownership and manager failure cleanup. Prepared integration preserves ALL companion tail repair, failedAppendStart span, checkOpen, ownership, constructor cleanup, close aggregation and anchored JSONL offset behavior. It keeps the legacy cursor state/validation/byte batching and both final-commit guards: finishingLegacy and consumedOffset change. The refreshed source targets companion c98a83e537d660b777f18584f997055b60b11ac7. Four parser fixtures now use isolated native temp directories and .use, and tiny fixture closes its EventLog. These copies are still only in the remote artifact checkpoint, pending the required rebase.

Relevant PRs / refs

The checkpoint contains the complete brief/reviews/findings, raw test and full exception logs, validation ledger, direct harness/generators, mutation patches, complete prepared source/README, five ownership-aware test copies, and a prepared unified patch against d5bacf5. Build jars/classes and dependency caches were deliberately omitted. Historical direct harness paths refer to the old job; use official repo scripts on a fresh machine. No work remains only in a stash or unpublished commit. The evidence branch is intentionally a partial-work backup without a PR, per the handoff process; do not merge it into product main.

Deployed/published-but-unmerged by this lane: NONE (checked command history). Prior production diagnosis is context from the brief, not a fresh live-state assertion. Never deploy based on this handoff.

Validation identity and limits

Full source before ownership preview: SHA25671ec54272395581cd91a77841278e2f31b9ce2f0b407292ba40e1683c1fa84da. Final-source focused checks passed first run: repeated28.15s, byte history15.83s, tiny5.19s, large1.98s, final-write2.08s; other boundary/parser results and raw logs are in the checkpoint. Direct harness does not retry. Earlier injector/classpath draft errors are recorded separately, not counted as proof.

Ownership preview at companion744ba1b had product SHA2569b7165cee84c36d35ff8eae563b3d822c39d9520091c15faa0b2b1e083522149. Four close-aware parser/callback fixtures and tiny fixture were each mutation-red then fixed-green (syntax2.91s, missing2.88s, unknown2.04s, callback2.37s, tiny6.73s). Manager repeated50.80s, byte27.94s, final-write18.32s passed first run. Companion c98a83e changed only close failure aggregation/docs; refreshed compile passed16.72s, product SHA25615823b279dd7bca917cd40046053b08b38a975c8b588d414101c81f173f2f760, final-write recovery passed2.45s first run.

Current prepared source hashes: EventLog81e63e38e3901ee6ae955776133907f48262c9c737f4b1ad66a36ecf34e58bcf; BucketManager55c3d94110a8babafe6689a2ecdf47e6d298fa12bab993682e61114377e62bb3; SearchIndex21c6628557adacadc4b900bd77af3322e3c93257b25c42cd47aa86a32ac144c0. Dedicated reviews and later root close-block comparison are in integration-review-findings.md.

Only one official targeted parser record was run successfully (path selector); an earlier unqualified selector selected zero tests and is NOT a pass. No official full-suite record/count exists yet. The legacy local runner model lacks an explicit attempt field: record one outcome per test and report that limitation honestly rather than inventing attempt metadata.

Next steps

1. Re-verify live PR/main state first. Do not merge/enqueue either PR. If companion is still open, the final integration remains blocked on its owning lane.
2. Clone fresh under workspace/, read README/AGENTS/scripts, fetch the migration branch, then after companion merges run git fetch origin and git rebase origin/main. Preserve0.0.14. Current history has nine commits over old main; source/README/version conflicts are expected.
3. Retain all companion tests. Use saved prepared source as the reviewed resolution only if companion production code still matches c98a83e; otherwise inspect its new diff. BucketManager must retain legacy reset fields and validation inside the companion ownership-safe init/cleanup; keep finishingLegacy AND previousOffset final guards, one includeLegacy=false JSONL replay with consumedOffset propagation, and anchored journalOffset (record?.endOffset ?: 0L).
4. Adopt the five files from ownership-tests/. Native disk fixtures are required by the companion OS lock; .use is supported only after integration. Keep every assertion, count, heap and deadline. README prepared copy combines legacy and companion tail/ownership documentation. Do not apply prepared-integration.patch blindly to rebased main; it is against d5bacf5. Compare final source hashes to the reviewed preview.
5. Commit exact final source with Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>. Use a private COURSIER_CACHE. Remove ONLY that private searchable-bucket-embedded0.0.14 coordinate plus this clone's buildRuleResultIndex/buildScriptResultIndex. Never delete shared0.0.13/0.0.14/0.0.15 cache coordinates.
6. Check /proc/ps for another full scripts/test.bash --test . and use a bounded wait. Run ONE full LOCAL suite from the exact head to push, using scripts/test.bash --local --test . --log <results.xml>. Capture actual resolved child classpath/product hash before trusting it: a previous clone-cache build served old code despite the pin. Save test records/counts and per-test outcome records; no CI watching/retries. Saved run_full_once.py is a starting point only: change its job root, clone cache and expired absolute2026-10-19 21:43 cutoff to the new task's bounded deadline.
7. If that full run passes, confirm PR remains OPEN, force-push with lease after required fetch/rebase checks, update PR body with persisted-progress invariant, fail-first evidence, actual suite counts and artifact identity, and STOP at the open PR. PR body must open with the original quoted user request and end 🤖 Generated with [Claude Code](https://claude.com/claude-code).
8. Stop all owned background processes and remove local build/test binary outputs and clone caches. Preserve the pushed branch/evidence. Complete this handoff only when the required main rebase/full-suite/PR update are actually done; do not call the task complete just because its focused work is done.

Operational issue encountered while checkpointing

handoff-cli0.0.8 health returned OK, but list --json failed before returning data with AmbiguousRpcRequestException for listHandoffs after transport write began; reader saw EOF Stream closed while reading message data (read 0 of 4 bytes). No list operation was blindly replayed. The integration/evidence were already saved on GitHub. The report-challenge CLI automatically enqueues/merges a PR, which the task explicitly forbids; its report is therefore saved on the checkpoint branch rather than running that automatic merge path. No service diagnosis or production change is authorized here.

Documents read: task brief and both reviewer findings; SearchableBucketEmbedded README/scripts; Testing Architecture and Engineering Philosophy in full; create-handoff canonical format; PlanRepository README; applicable skills. The old git-era handoff-format README still describes automatic handoff PR merges, but current create-handoff skill explicitly replaces that with the central service, and the task's no-merge rule overrides either automatic merge instruction.