Situs guest cards: the window and the cadence

src/lib/integrations/appfolio/writers/guest-cards-portfolio.ts:82 calls wideYearRange(), defined at src/lib/integrations/appfolio/pms-adapter.ts:2706:

export function wideYearRange(): [string, string] {
  const today = new Date();
  const from = new Date(today); from.setUTCFullYear(today.getUTCFullYear() - 1);
  const to   = new Date(today); to.setUTCFullYear(today.getUTCFullYear() + 2);
  return [from.toISOString().slice(0, 10), to.toISOString().slice(0, 10)];
}

Anchored on wall-clock now, and nothing else. No cursor, no stored state, no per-account value. The same function is the window on the per-property fallback path (pms-adapter.ts:942, listGuestCards), so both paths agree.

Trinity's "three-year window" is the parameter span — one year back plus two years forward. The effective data window is about one year back: the forward edge buys nothing on a report filtered by a received date, because no card is received in the future.

Is there a watermark it could anchor on instead?

No. Nothing records a last-successful-pull for guest cards. What exists and does not serve:

• The quiet-pass memo (src/lib/domain/pms/quiet-pass.ts) holds inputHash + passAtMs per property and job. It is computed from the already-fetched rows (handler.ts:5129–5163), so it records what the last pass saw — it is not a bound the next fetch could use.
• PmsRecord.last_seen (src/lib/data/dynamo/pms-records.ts) is per mirrored card, refreshed hourly. Per row, not per pull.
• The report snapshot cache (src/lib/integrations/appfolio/report-snapshot-cache.ts) lives exactly one Lambda invocation. Its own header says a cross-tick cache "would need its own staleness story this module deliberately does not take on."
• The purchase-order watermark (src/lib/data/dynamo/purchase-orders.ts, PurchaseOrderSyncWatermark.lastSuccessAt) is the closest shape in the repo — but it exists for absence detection, not windowing, and its own window function says outright: "There is no updated_at cursor on the purchase_order report, so every tick is a full refresh of this window."

What I could not establish: guest_cards' own filter axis. The repo's AppFolio report catalog (.claude/skills/appfolio/reports-catalog.json) carries only {"id": "guest_cards", "name": "Guest Card Interests"} — no parameter semantics. Settling it needs two read-only Reports API GETs against situsgroup comparing row counts at from_date=2000-01-01 versus from_date=today-1y. I did not spend the budget tokens on an account already being refused. That measurement is the fix lane's first step, and it decides the window half.

Not the expression field in schedules.json. That reads rate(15 minutes) for guest_cards and is dead text. Read live from AWS:

$ aws events list-rules --name-prefix propflow
propflow-appfolio-sync-prod-class-act-now-schedule | rate(1 minute) | ENABLED

$ aws events list-targets-by-rule --rule propflow-appfolio-sync-prod-class-act-now-schedule
Arn:   arn:aws:lambda:us-east-1:194925971150:function:propflow-appfolio-sync-prod
Input: {"jobs": ["work_orders", "rental_applications", "guest_cards", "guest_card_messages"]}

There is no propflow-appfolio-sync-prod-guest-cards-schedule rule. Positive control on that absence: the same listing did return …-vendors-schedule and …-wo-enrichment-schedule — per-job rules that still exist, because vendors is individually DISABLED (so not superseded) and wo_enrichment carries excludedFromClasses. The sweep can see per-job rules; guest-cards' is genuinely gone.

So the cadence is schedules.json's classes.act_now = "rate(1 minute)" — a platform default applied to every customer, not anything about situsgroup. ensure-schedules.sh:139–145 retires the per-job rule for any classed, enabled job. docs/integrations/appfolio.md:232 records the change in plain words: "guest_cards 15min→1min", shipped by #8136 on Fede's 2026-09-12 cadence-class ruling.

The quiet-pass skip is not the missing suppressor

The brief asked whether the skip should be suppressing these runs and is failing for situsgroup. Two independent answers, both no.

(a) It structurally cannot. handler.ts:5129–5135 drains the fetch into guestCards[], and then :5149 hashes that array. The hash input is the fetch result. The gate at :5429 runs after the AppFolio request has already been paid for. #16738 was always a DynamoDB-side optimisation — its own header says so: "that is ~2 reads per card per minute that can only ever confirm what the last minute already found."

(b) It is firing, and firing well. 30 minutes of pms GuestCardSync[quiet-pass] lines for situsgroup properties, uncapped sample (1,490 lines returned against a 3,000 cap), 52 distinct properties:

Re-verified for situsgroup.appfolio.com from the handler's own guest_cards portfolio-wide fetch info line, 24 hours to 2026-10-23T01:26Z:

Where guest cards actually sit in the spend

All portfolio-wide fetch lines for appfolio#situsgroup#86fe, 24 hours. Denominator caveat: these are the sync Lambda's fetches only. durable-account-budget.ts's own header names other drawers on the same bucket — the availability heartbeat, Clara's live tools, and concurrent invocations — so the account's true draw is higher and is not measured here.

Guest cards are 21% of the sync Lambda's spend, not the whole budget. The three act_now one-minute jobs together are 4,301 requests — 64%. The durable bucket's capacity is 6 tokens per 15s (durable-account-budget.ts: DEFAULT_CAPACITY = 6, DEFAULT_REFILL_WINDOW_MS = 15_000) = 24/min = 34,560/day, so 6,675/day is about 19% of capacity from this Lambda.

For the sibling lane (diagnose-budget-pause), not for this row

Three things I noticed and deliberately did not chase:

Rename the row. "Incremental guest-card window" is the wrong fix, and building it would be a regression. Two independent changes, and they are coupled in ordering.

A — the window: WIDEN it, mirroring #20139 exactly

Correctness. Costs no extra requests.

1. Measure first. Two read-only Reports API GETs on situsgroup: guest_cards with from_date=2000-01-01 versus from_date=today-1y, status: 'all' on both. Differing row counts prove the back edge is hiding cards and settle the filter axis in one shot. scripts/guest-cards-portfolio-dryrun.ts already exists as the read-only harness.
2. If they differ: swap wideYearRange() → pmsHistoryWindow() in both paths (writers/guest-cards-portfolio.ts:82 and pms-adapter.ts:942), and add the writer-side lookback predicate alongside it — the isWithinEverydayApplicationWindow seam from #20139 — so the mirror holds every card while the prospect writer's input is unchanged. #20139's own diff is the template, file for file.
3. Re-verify requests stays 1 after widening. A bigger payload could cross a page boundary; today's single request is measured on the narrow window, not the wide one.
4. Regression test that fails on the bug: a card received outside today−1y must reach the mirror.

B — the cadence: a pre-fetch per-account cooldown, the financials shape

Cost. Needs a founder's ruling.

The only shipped way to cut the request count without touching the global class cadence is already in this Lambda, from Gera's 2026-09-18 decision b89703990 / #9372: financials ticks hourly but reads AppFolio once per property per day, by consulting a durable cooldown row before the fetch.

• src/lib/data/dynamo/financials-sync-cooldown.ts — the row.
• isFinancialsFetchDue(lastSuccessAtMs, nowMs) — src/lib/pms/run-financials-sync.ts:132.
• Read at handler.ts:6435, declines with summary: { skipped: 'financials-cooldown' }, stamped at :6538 only on a run that reached the source — a failure leaves the stamp alone, so an outage costs one tick, never a whole interval.

Copy it as a per-account (accountFingerprint) cooldown for guest_cards, consulted before fetchGuestCardsPortfolioWide at handler.ts:4737, with a guest-cards-cooldown skip reason added to the existing taxonomy at handler.ts:425. The class rule, its target Input and every other job stay untouched. At a 5-minute interval that is 1,423 → ~288 requests/day for this account; at 15 minutes, ~96.

C — one-line doc fix, free

guest_cards' expression: "rate(15 minutes)" in lambda/appfolio-sync/schedules.json has fired nothing since #8136 and reads as the live cadence to anyone who opens the file — it is what the audit read. Either strip the inert expression from classed jobs, or comment it the way guest_card_messages' own notes block already does.

1. Which date column guest_cards' from_date filters on. Measured for rental_applications (Received, #20139) and work_order (CreatedAt, history-window.ts); inferred, not measured, for guest_cards. Two read-only GETs settle it.
2. Whether situsgroup actually holds guest cards outside today−1y. Same measurement. #20139 found 21 such applications at this customer, which makes it likely, not proven.
3. The 2026-09-29 16:00Z onset hour. #8136 made this one-per-minute on 2026-09-13 — sixteen days before the symptom — so the guest-card cadence alone does not explain the onset either. (Nor do #14255 or #14072: both merged 2026-09-30, a day after.) That belongs to diagnose-budget-pause.
4. Whether the act_now burst, rather than the day's total, is what empties the bucket. 19% average capacity with 118 refusals/day says it must be burst, concurrency or an unmeasured drawer, but this was not measured at 15-second granularity.