Skip to content

#172: flip substrate search to default; ?fts=off escape hatch#335

Merged
rdhyee merged 4 commits into
isamplesorg:mainfrom
rdhyee:feat/fts-default-on
Jul 17, 2026
Merged

#172: flip substrate search to default; ?fts=off escape hatch#335
rdhyee merged 4 commits into
isamplesorg:mainfrom
rdhyee:feat/fts-default-on

Conversation

@rdhyee

@rdhyee rdhyee commented Jul 17, 2026

Copy link
Copy Markdown
Contributor

🤖 rbotyee (Claude, operated by @rdhyee) — Raymond's intent: "ship the most recent progress unless it's obviously broken, with a flag back to the version we think might still be better" (decision 2026-07-17 AM, pre-meeting). What I did: implemented the minimal default-flip + escape hatch, updated the e2e spec, and staged the SME ranking comparison as the post-ship tuning input.

What changes

  • Substrate FTS becomes the default search path — substrateEnabled() now returns true unless ?fts=off.
  • ?fts=off is the escape hatch back to the interim ILIKE scan (kept fully intact as rollback + A/B baseline).
  • ?fts=v1 still accepted — every pre-flip opt-in link behaves identically.
  • Spec: the old "no param → interim" test becomes "?fts=off → interim"; new test asserts "no param → substrate" (basalt = 785, 202608 ground truth).

Why ship now (honestly)

  • Substrate wins every benchmark row vs interim (#171 post-fix table): pottery 22.3s → 11.6s cold, no-hit 62.7s → 5.5s. No more 69 MB first-search download.
  • All #172 hard-fail invariants pass.
  • Hand review of the benchmark top-10s this morning found no glaring ranking regressions (RY: "can't tell the difference" — recorded as a datum, not a rubber stamp).
  • Ranking quality is tunable post-ship: an SME A/B comparison sheet (side-by-side top-10s + live paired links per query) goes to Andrea/Eric/John today; their verdicts calibrate the Explorer FTS Track 5: GO/NO-GO decision gate #172 thresholds and any BM25/field-weight tuning, with no index-format change required.

What this does NOT do

  • Does not close Explorer FTS Track 5: GO/NO-GO decision gate #172. The §7 end-to-end budgets stay open as the pin-overlay / downstream-latency track — both backends miss them today because post-search surface refiltering (shared, pre-FTS) dominates. Flipping the default is a relative ship decision (strictly better than baseline), not a §7 pass.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Nohddj7oXLnkJ4P9Cibg8Y

rdhyee and others added 4 commits July 17, 2026 06:23
@rdhyee @claude
isamplesorg#172: flip substrate search to default; ?fts=off escape hatch
209e5da 
Ship decision 2026-07-17 (RY): most recent progress ships unless obviously
broken, with a flag back to the prior path. Rationale:

- Substrate wins every benchmark row vs interim (isamplesorg#171 post-fix table,
  e.g. no-hit 62.7s -> 5.5s cold; pottery 22.3s -> 11.6s).
- All isamplesorg#172 hard-fail invariants pass (stopword equivalence, duplicate-term
  identity, concept-only non-empty, no-hit zero, tokenizer parity).
- Hand review of benchmark top-10s (2026-07-17 AM) found no glaring
  ranking regressions; SME A/B comparison sheet goes out today as the
  post-ship ranking-quality input (calibrates isamplesorg#172 thresholds; BM25/field
  weights tunable post-ship without index format changes).

Mechanics:
- substrateEnabled(): default true; only `?fts=off` reverts to the interim
  ILIKE scan (kept intact as rollback + A/B baseline). `?fts=v1` still
  accepted, so pre-flip opt-in links behave identically.
- Spec: 'no param -> interim' becomes 'fts=off -> interim' (escape hatch),
  plus a new 'no param -> substrate' test asserting the flip (basalt 785).

The isamplesorg#172 gate does NOT close: Section 7 end-to-end budgets remain open as the
pin-overlay / downstream-latency track (both backends miss them today;
the dominant cost is shared post-search refiltering, not the backend).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nohddj7oXLnkJ4P9Cibg8Y
@rdhyee @claude
isamplesorg#172 flip, Codex round 1: PID routing + rollback/retry har…
5332e89 
…dening

- P1: PID-looking queries (ARK/IGSN/DOI/resolver/pid:) route to the interim
  builder even under default substrate — the substrate index has no PID field
  (SEARCH_INDEX_V1 s2), so tokenizing a pasted identifier returned junk.
  Interim's exact-PID arm (isamplesorg#278/isamplesorg#26) handles it. New no-flag Playwright
  regression using a PID from the interim benchmark's own top-10.
- P2: ?fts=off now dominant over duplicate params (getAll, not first-wins).
- P2: a REJECTED substrate module import resets the cache so the next search
  retries instead of failing forever on one transient hiccup.
- P2: routing tests moved to their own describe (no double cold-boot via the
  ?fts=v1 beforeEach); stale opt-in comments updated; "exactly as interim"
  overstatement corrected.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nohddj7oXLnkJ4P9Cibg8Y
@rdhyee @claude
isamplesorg#172 flip, Codex round 2: CI budget + comment accuracy
f3e7b8d 
- explorer-e2e dispatch job cap 20 -> 35 min: fts-v1 spec worst-case is
  20m30s of test budget alone (5x120s substrate, 150s default, 2x240s
  interim-path routing) before install/render; a slow dispatch run was
  killable mid-suite with no diagnostics.
- Contract comment: display-column backfill joins samples_map_lite, not
  the wide parquet.
- Interim builder comment: isamplesorg#171 landed and is default; this path now
  serves ?fts=off rollback + PID-looking queries, not "goes away".

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nohddj7oXLnkJ4P9Cibg8Y
@rdhyee @claude
isamplesorg#172 flip, Codex round 3: retry envelope + last stale comm…
2d587c7 
…ents

- fts-v1 spec caps itself to 1 CI retry (file-level configure): 2 attempts
  x 20m30s = 41m envelope; workflow dispatch cap 35 -> 55 min so retries
  and artifact upload survive a data outage.
- A1 strategy header and warm-buffer comments now state the substrate
  default vs interim (?fts=off / PID) split instead of universal ILIKE.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nohddj7oXLnkJ4P9Cibg8Y
@rdhyee rdhyee added the CC+Codex+LGTM Claude and Codex both reached LGTM; ready for human review label Jul 17, 2026
@rdhyee

rdhyee commented Jul 17, 2026

Copy link
Copy Markdown
Contributor Author

🤖 rbotyee (Claude, operated by @rdhyee) — Raymond's intent: Codex sign-off gate before merge. What I did: ran 4 adversarial Codex review rounds on this PR; posting the final verdict.

Codex review: LGTM (round 4; 0 P0 / 0 P1 / 0 P2)

Round 1 (NOT-LGTM) caught a real ship-blocker: PID-aware search (pasted ARK/IGSN/DOI) would have regressed under the default flip — the substrate index carries no PID field. Fixed by routing PID-looking queries to the interim builder's exact-PID arm, with a no-flag Playwright regression.

Rounds 2–3 hardened the edges: ?fts=off dominant over duplicate params; rejected module-import no longer cached forever (retry works); routing tests no longer double-boot; CI retry envelope now fits the dispatch job cap (1 retry × 20m30s spec budget, 55-min cap); all opt-in-era comments updated.

Round 4 verification: 110 unit tests + 40 frontend-derived tests pass, Playwright discovers all 8 cases, clean diff. (Live remote E2E not executed in the review sandbox; will verify on production post-merge.)

@rdhyee
rdhyee merged commit df0ea25 into isamplesorg:main Jul 17, 2026
2 checks passed
This was referenced Jul 17, 2026
Open
Merged
rdhyee added a commit that referenced this pull request Jul 17, 2026
@rdhyee @claude
#268 docs: update search walkthrough for the FTS default flip (#335)
c41e9ad 
EXPLORER_QUERIES.md still described the ILIKE facets scan as THE search
path; since 2026-07-17 that is only the ?fts=off / identifier fallback.
Adds the sharded-index default path in plain English (Eric's #268 ask),
the search-index row in the file table, and relabels the try-it-yourself
ILIKE example as the fallback equivalent.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nohddj7oXLnkJ4P9Cibg8Y
This was referenced Jul 17, 2026
Open
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

CC+Codex+LGTM Claude and Codex both reached LGTM; ready for human review

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Explorer FTS Track 5: GO/NO-GO decision gate

1 participant

@rdhyee