E-rate Contract Evidence & Extension Monitor

Turn official USAC Form 471 evidence into one record per exact applicant BEN + USAC contract ID. Compare reported expiration dates, extension terms and funding-status edits across complete observations, with CSV exports and underlying FRN provenance. Use it for bounded E-rate contract research and recurring evidence checks.

Start with one applicant BEN or a narrow state/provider scope. A first complete observation seeds the monitor; later observations return new contracts and semantic changes. An unchanged observation still produces a complete contract export.

Reported dates are not confirmed renewal or rebid deadlines. The extended date is not asserted to be exercised, maximum, or later than the contract end. Historical FRN provider SPIN/name is not asserted to be the current incumbent. No contract lifetime value is computed from annual FRNs.

Bounded example

The Store trial prefill uses one verified BEN (17027710), empty state filters, at most five contracts and 1,000 rows. Clear that sample BEN when switching to a state/provider-only input. API calls with no BEN/SPIN filter default to NY; supply an explicit bounded scope for a first trial.

{
  "bens": ["17027710", "130359", "132748"],
  "fundingYears": [2024, 2025, 2026],
  "monitorName": "contract-evidence-test",
  "maxContracts": 10,
  "maxRawRows": 1000,
  "maxRunSecs": 180
}

Omit states when using BEN/provider filters. Without BENs/SPINs, the default is one state (NY). At most one state, 100 BENs and 100 nine-digit provider SPINs are accepted; dimensions combine as AND, selections within one dimension as OR. Funding years are explicit or default to the current UTC year and previous two, at most ten years. Optional reportedEndFrom/reportedEndTo bound reported end dates inclusively. Keep discovery scope/date bounds fixed per monitor; funding years may roll forward.

Discovery requires Current + Funded + Contract and a Category 1 service (Data Transmission and/or Internet Access or historical Voice). It excludes Original, denied/cancelled, tariff/month-to-month and Category 2. Missing contract IDs remain unresolved; matching by name, provider or contract number is prohibited. Selected contracts' exact history is fetched across the chosen years without discovery date/provider/status restrictions. Previously watched identities stay watched even when dates leave the window or funding status changes.

Evidence and changes

• One exact contract record contains its underlying Current FRNs, annual statuses, latest funding year, applicant/state, historical provider name/SPIN, reported/extended dates, extension wording/counts, source URLs and snapshot/retrieval times. Original rows are counted/excluded, and exact duplicate copies are deduplicated.
• Conflicting latest-year dates remain arrays; the single date is null when no unique value exists. Invalid dates/counts stay unknown with flags. Raw date strings remain in FRN evidence. The real 2030-06-30 vs 2025-06-30 and 2028-01-31 vs 2028-01-30 examples remain separate and flagged.
• A historical Form 470 joins only when establishing_form_470 == application_number and BEN equals billed_entity_number. Original historical forms are explicitly labeled. No new Form 470 is inferred to replace a contract.
• First complete read seeds history. Later complete reads emit newly observed contracts and exact semantic date/extension/provider/funding-status changes. New annual FRNs, funding-year rollover and elapsed time alone do not emit changes. Existing FRN status edits are compared even in older years. A denied FRN is not labeled a cancelled contract.
• Missing FRNs/contracts retain last-known-good evidence with observedThisRead: false, original retrieval time and a carry-forward flag. They do not create a disappearance/cancellation event. currentFrnCount includes retained last-known-good evidence; observedCurrentFrnCount counts rows seen in this read. Review coverage and flags before using stale evidence.

Completeness and persistent monitoring

Anonymous USAC SODA2 FRN data and historical Form 470 data supply projected fields. Their schema metadata/rowsUpdatedAt is read before and after all pages/joins. Missing metadata, schema changes, refresh races, repeated pages, source errors and caps produce complete: false and preserve the baseline. Snapshot publication is separate from extraction.

Hard maximums: 1,000 watched/discovered contracts, 50,000 raw rows across all source reads, 10 MB per response and 10 MB snapshot, 60 seconds/request, two concurrent HTTP calls, and three attempts with capped 429/503 backoff. Default run source budget is 120 seconds, maximum 180; the cloud runtime additionally reserves 15 seconds for final output. A full page exactly at the raw-row cap is treated as incomplete because exhaustion was not proven. Limits do not silently publish a truncated baseline.

Cloud history uses a named KVS in the run account, or an empty dedicated historyStoreId selected with READ/WRITE grants. API metadata must identify the current run account as its owner. Shared or foreign-account stores and stores with unrelated keys are rejected; existing-user ownership is tested, while a second customer account has not been used. A dedicated RequestQueue singleton is locked server-side using a run-specific client key. A resurrected run reclaims its own unexpired lease by server-verified renewal; a different run cannot renew that lease; the lock is checked/renewed before source requests and publication. KVS reads are bounded to 20 seconds with one retry; record writes use a 15-second timeout without timeout retries. The lease is renewed immediately before final pointer reads/writes and must have at least 90 seconds remaining. A separate default-run-store recovery marker prevents a pruned prepared journal from being silently rebuilt. The immutable content-addressed snapshot is verified before a single-record LATEST pointer PUT. Run journals recover lost write responses; stale prepared runs cannot roll a newer baseline back. Retained snapshots link through previousSnapshotKey; an older link may point to a pruned record.

Local storage uses an exclusive file lock and atomic pointer rename. A crashed local process can leave storage/erate-history/<monitor>/LOCK; inspect its PID before manually clearing it. Do not delete history casually. History keeps the eight newest snapshots plus the current baseline and active recovery candidate: at most ten snapshots and ten associated journals, plus three metadata/pointer records. Each snapshot is capped at 10 MB, so retained snapshot payloads are bounded to 100 MB per monitor. Cleanup validates digests and the dedicated-store marker before deleting only recognized snapshot/journal records. Unrelated records, corruption or a 128-key scan limit fail closed. A denied cleanup after publication is reported as retentionCleanupPending; the next run retries cleanup before source work. Named storage continues to incur storage cost while idle. Recent same-run recovery is supported while its journal and default run storage remain available; default platform retention also applies. Older prepared runs fail with run_journal_expired; start a fresh run. No indefinite archive is promised.

Dataset/export writes happen from a prepared candidate before publication. Native export records and actual dataset rows are read back and checked against exact expected hashes before publication; delivery intent and verified acknowledgments are saved and read back in the default run store. An uncertain partial or invisible append is never repeated; recovery waits for the complete originally requested batch to become visible and stops baseline advancement until verification. An undated legacy prepared run without this delivery protocol requires review while its dataset is incomplete. An incomplete run may have prepared exports/rows, but its report explicitly says no new baseline was published. Use OUTPUT.complete: true and baselinePublished: true as the complete observation. If the final OUTPUT write fails after publication, ERROR explicitly says the baseline may already be committed; resurrect the same run to reconcile its persisted candidate and recover the report. Do not assume every FAILED run leaves the previous baseline unchanged. Snapshots contain all last-known-good evidence; dataset and change export contain baseline/new/changed rows only.

Files and validation

CONTRACTS.json and spreadsheet-safe CONTRACTS.csv contain all retained contract evidence. CHANGES.json/.csv contain output changes/baseline rows. UNRESOLVED.json preserves missing identities. OUTPUT reports limits, completeness, source versions, observed/carried-forward counts, snapshot key, history store and pricing status. Nested exact changes and per-FRN provenance are best consumed as JSON.

Run npm test for offline acceptance tests. npm run sample executes the captured public fixtures and writes native exports in artifacts/; it makes no source requests or cloud runs. Fixture provenance is in test/fixtures/PROVENANCE.json. A live bounded private acceptance build/run is separate evidence; inspect the release report for its actual status and costs.

Price and spending limits

$0.01 per contract in a completed snapshot ($10 per 1,000 contract snapshots), including unchanged contracts. For example, a complete seven-contract observation costs $0.07 even if it has no changes. The price counts every contract in CONTRACTS.json, including explicitly flagged last-known-good evidence retained from an earlier read. It does not count FRNs, annual funding years, changed fields or source requests separately. Empty complete snapshots count zero units. There are no actor-start or automatic dataset-item events, and no separate runtime-usage surcharge is requested.

Before delivery, the actor checks that your maximum run charge covers the entire selected/watched snapshot. If it does not, the observation stops without charging or publishing a new baseline; raise the cap or choose a narrower scope with a new monitor. maxContracts is a completeness guard: it does not silently truncate results. For a first trial, use one BEN and a maximum charge of at least $0.05 for the five-contract prefill. Invalid input, source errors, incomplete extraction and unverified delivery create no contract-snapshot charge.

A billable snapshot has verified native exports and dataset rows, a verified history pointer, and a verified complete OUTPUT report. Charging follows that completion. An interrupted run can therefore leave completed data awaiting billing. A late report/storage error can also make a run fail after a completed snapshot was charged; the completed data and BILLING_STATE receipt are retained. Check OUTPUT.complete, baselinePublished, pricing.status, pricing.unitCount and BILLING_STATE rather than assuming run status alone means charged or uncharged. An unchanged run has zero change rows in the dataset but its full contract export is still the billable result.

The actor writes and verifies a charge intent before its single full-snapshot event batch, and verifies a durable acknowledgment afterward. An acknowledged same-run recovery does not charge again while its journal and run storage are retained. A lost response may be retried with the same key only within a conservative two-minute window; the platform key expires after three minutes. Older ambiguous charges stop for review without another POST. Starting a fresh run is a fresh observation and can incur a fresh charge. Storage and charging have no shared transaction, and indefinite exactly-once recovery is not promised. Legacy unpriced prepared runs cannot be retroactively billed.

Apify storage retention and ordinary access to stored datasets/key-value records still apply; named monitor history remains stored between runs. Review your Apify usage and narrow or retire monitors you no longer need. Pricing does not establish buyer demand or willingness to pay.

No contacts, applicant directory redistribution, annual FRN cost sums, browser, proxy, OCR, LLM, enrichment or outreach are included. This actor preserves reported evidence; it does not predict procurement, confirm renewal deadlines or identify a current incumbent.

Validation and recovery

Run npm test for source/semantic/storage acceptance, billing fault simulations, and real local process-interruption tests. Public fixture provenance is in test/fixtures/PROVENANCE.json. The release report records the exact private cloud build, scenarios, costs and remaining limitations; local simulations do not prove cloud billing permissions or a second customer's storage grants. examples/output-priced-complete-illustrative.json is an actual-runtime offline illustration with mocked charging. The older output-complete-unchanged.json and output-incomplete-cap.json retain genuine historical unpriced cloud evidence and do not claim paid acceptance.

For an incomplete read, inspect OUTPUT, narrow the scope or increase the relevant bounded cap, and start a fresh run. For a completed run with an unconfirmed recent charge or report failure, recover the same run while its retained state is available. An expired ambiguous charge requires review, not an automatic replay. Shared or foreign-account history stores are refused.