Skip to content

runtime.md

Latest commit

 

History

History
230 lines (163 loc) · 5.46 KB

runtime.md

File metadata and controls

230 lines (163 loc) · 5.46 KB
Raw

Runtime Strategy

Most runtime policy knobs now live in ~/.finch/config.json.

That includes:

  • cache TTL baselines
  • hydrate batch size
  • search and collection page caps
  • low-yield thresholds
  • duplicate frontier threshold
  • pressure stop threshold

The shipped defaults in config.example.json match the current production behavior.

High-level flow

For collection commands, finch follows this model:

  1. Build a normalized request fingerprint.
  2. Try cache first unless --live is set.
  3. Choose the healthiest cookie for the endpoint family.
  4. Fetch the discovery surface.
  5. Normalize results.
  6. Hydrate discovered entities through batch endpoints when needed.
  7. Continue pagination while the source is still productive.
  8. Save cache, cookie observations, and optional cursor state.

Endpoint families

The runtime treats these as separate traffic classes:

Family Typical commands
search search posts, search users
profile user posts, user media, user articles, user highlights
list list posts, list members
article article get
hydrate batch tweet/user hydration
deep tweet thread and edit-history reads

Each family gets its own cookie health and request observations.

Cookies and routing

Cookies are used as a session pool, not blind round-robin rotation.

Cookie selection priorities

  1. Better family-specific health score
  2. Lower recent usage for that family
  3. Last-good cookie pinned by saved cursor state when resuming pagination

This means:

  • a search-heavy cookie does not have to carry profile traffic
  • resumed pagination can stay on the same good session
  • one bad cookie does not poison all families equally

Cookie health signals

finch tracks:

  • success/failure counts
  • recent 429s
  • suspicious responses
  • remaining/limit headers when available
  • reset timestamps
  • observed latency

Hydration strategy

Discovery surfaces do not always return the richest payloads. finch therefore hydrates in batches.

Internal batch endpoints

Endpoint type Current runtime role
TweetResultsByRestIds Tweet hydration
UsersByRestIds User hydration

Current default batch size

finch currently uses a default hydrate batch size of 400.

Why:

  • exact batch hydration is cheaper than many single-entity calls
  • live tests proved much larger payloads work
  • 400 is a strong production default without pushing to the observed upper edge every time

This value is configurable through:

{
  "hydration": {
    "default_batch_size": 400
  }
}

Exact vs collection behavior

  • Collection commands can keep bonus items from a final page.
  • Batch commands are exact: only requested ids should be returned.

Cache and TTL

Cache tiers

Tier Purpose
frontier First-page collection results and hot surface reads
surface_page Deeper paginated surfaces
entity Single entities and stable records
derived Derived result sets such as people-search shaped outputs
failure Thin, empty, or suspicious responses

Dynamic TTL inputs

TTL is not just a fixed number. It is adjusted using:

  • cache tier
  • endpoint family
  • page depth
  • returned count
  • requested limit
  • whether the result is thin/empty
  • family pressure
  • response confidence

The base TTLs are configurable through:

{
  "cache": {
    "tier_ttl_s": { "...": 0 }
  }
}

The finer-grained dynamic multipliers remain internal defaults in code.

Baseline behavior

  • thin or empty results get shorter TTLs
  • deeper pages get longer TTLs
  • high pressure raises TTL to avoid hammering X again immediately
  • low-confidence payloads get shorter TTLs
  • stable entities live longer than hot first-page frontiers

Adaptive pagination

finch no longer uses a flat internal page cap as the main strategy.

Core rules

Pagination continues while all of these are still true:

  • target not reached
  • cursor still exists
  • frontier is not looping
  • page yield is still useful
  • family pressure is not too high
  • hard safety cap is not exceeded

Stop reasons

Typical stop reasons:

Stop reason Meaning
limit_reached Requested target reached
exhausted_source No next cursor / no more source content
duplicate_frontier Same frontier is repeating
low_yield_stop Consecutive pages added too little new value
pressure_stop Runtime pressure says stop live paging
cursor_missing Cursor could not be advanced

All of the pagination hard caps and thresholds are configurable through:

{
  "pagination": {
    "search": { "...": 0 },
    "collection": { "...": 0 },
    "yield_rules": { "...": 0 },
    "thresholds": { "...": 0 }
  }
}

Bonus behavior

For collection commands:

  • --limit is a target, not a hard cut
  • if the final productive page pushes the total over the target, the extra rows are kept

For exact trimming:

--strict-limit

Search author filtering

For from: search queries:

  • X search is still used for discovery
  • finch post-filters top-level authors
  • this makes single-author and multi-author from: queries strict even when X search ranking is loose

Cursor persistence

Collection commands can persist cursor state with:

--save-cursor

Saved state includes:

  • request fingerprint
  • endpoint name
  • cursor value
  • page depth
  • last-good cookie id

This makes resumed pagination more stable and less random.