Repository navigation
Releases
v0.4.11
v0.4.11
This release bounds MCP status responses, fixes compatibility provider searches for common
names, and adds optional lowest-premium, payment-permission and private admin tools. The new
route, tool and plugins are off by default. Migration 995 adds two empty derived-data tables.
The status plugin moves to 0.1.6 and needs a new approved-package hash. See Upgrading below.
What users notice
- MCP
get_statusreturns aggregate counts by default and stays below 64 KiB. Usesection,
offsetandlimitfor paged details. Oversized rows are omitted and counted, with
truncated: true. Paged source details includepublished_atandpublished_from; the
summary keeps aggregate counts. REST status responses keep their existing shape. - Opt-in
GET /v1/lowest-premiumsand MCPget_lowest_premiumsfind the lowest gross
on-exchange silver premium for one age, year and location. They require complete pricing
evidence, use exact derived cells when current, and otherwise rate every candidate. Ties and
evidence are paged; MCP reports omitted oversized rows while keeping the winner and amount.
Subsidies are not evaluated. - Optional
@openplans/plugin-msotresolves an operator'scustom_payment_allowedflag beside
public plan facts through/msot/resolveand MCPmsot_resolve. It requires a reviewed inline
source. Missing evidence stays unknown; the flag does not establish insurer payment acceptance. - Optional
@openplans/plugin-adminadds a private operator overview at/admin, protected by
the operator bearer credential. A separately configured HTTPS origin enables sign-in,
expiring browser sessions, sign-out and recent authentication forms. Keep the admin routes
behind a reviewed private ingress. The configuration page shows reviewed settings and drafts
proposals without applying them. Coverage and freshness shows loaded scope availability.
Metrics reports bounded current-process HTTP and MCP counts, latency histograms and cache
counters when collection is enabled. Releases and recovery reads versioned deployment
receipts and reports release, audit, backup and restore observations. Missing evidence stays
unknown; sections without an installed capability show an unavailable page.
Fixes
- Compatibility provider searches use the search keys for matching identities without located
addresses too. This fixes timeouts for common-name searches such as SMITH near ZIP 77002.
Results and counts keep their existing meaning. No new provider-key backfill is needed. - The admin package builds to its declared output path, so the host can load it. Container
builds retain the admin coverage source module while excluding generated coverage reports.
Upgrading
- Run
worker migratebefore starting the new API. Migration995_handy_lowest.sqladds two
empty tables and their metadata; older images ignore them. Its number is below migrations
already shipped, so check pending migrations by filename rather than the highest number.
No lowest-premium build or data import is required while the feature is off. - Update the approved-plugin entry for
@openplans/plugin-statusfrom 0.1.4 to 0.1.6 with the
rebuilt package hash. Read the version andsha256from the new image's
/status/operator.json, as indocs/plugins-operations.md, before replacing the entry. OPENPLANS_LOWEST_PREMIUMSstays off unless set toon. The new@openplans/plugin-msot
and@openplans/plugin-adminpackages are not loaded by default. Enable them explicitly
through the plugin configuration only after reviewing their setup. Browser admin sessions
also require the private HTTPS ingress configuration. These options stay off on the hosted API.
OpenPlans v0.4.10
This release fixes the MCP get_status tool. The status plugin moves to 0.1.4, so an approved
plugin list needs its new hash. There is no migration and no new backfill.
Fixes
- The MCP
get_statustool works again; it leaves out the per-source publisher dates, which
stay in/status.json. In v0.4.9 a server with several hundred sources answered
get_statuswithRESULT_TOO_LARGE: the two new date fields pushed the answer past the
128 KiB MCP limit. The tool now returns the same fields as in v0.4.8./status.json,
/status/operator.jsonand the status page still showpublished_atandpublished_from.
Known issues
- On the hosted API, a compatibility provider search for a common name near a large city, such
as SMITH within 25 miles of ZIP 77002, can still answer 504. The same search through
/v1/providersanswers in time.
OpenPlans v0.4.9
This release makes compatibility provider searches for common names answer in time, shows each
source's publisher date on the status page, keeps words whole in its tables on phones, adds a
read-only check for newer publisher files, and makes Census downloads work again with the
shipped access manifest. The status plugin moves to 0.1.3, so an approved plugin list needs its
new hash. There is no migration and no new backfill. Search results don't change, though some
searches that answered 504 now answer in time. /status.json only adds fields. See Upgrading
below.
What users notice
- Compatibility provider searches for common names answer in time. A compatibility location
search for a name such as SMITH, or with a taxonomy, specialty or type filter, now reads the
provider search keys when 2,000 or fewer identities match in the radius. On a nationwide NPPES
load such a search answered 504 in v0.4.8. Results, totals and pages are the same as before.
Searches with more matches, or with no filter, keep the original path, which reads fewer rows
for them. - Status tables keep words whole on phones. At 390 px and narrower,
/statussplit words
across lines, such as "Catal/og" and "unavailabl/e". Table cells now wrap only at spaces. Only
source IDs, snapshot IDs, times, hashes and event payloads can still break mid-token. A table
that is wider than the screen scrolls sideways inside its own region, which you can reach with
Tab and scroll with the arrow keys. The page itself never scrolls sideways. - The status page shows when each publisher released its data. "Retrieved" says when
OpenPlans fetched a source, so "retrieved 3 days ago" could read as "up to date". Each source
group now shows Published next to Retrieved, and its summary line gives the range of publisher
dates. The date comes from what the import stored: the publisher's release date (an RxNorm
release, an NPPES file date, a Medicare or Part D release label) first, else the file's
Last-Modifieddate./status.jsonand/status/operator.jsonadd two fields per source:
published_at(YYYY-MM-DD) andpublished_from(release_dateorlast_modified). Both
arenullwhen the date is unknown. Every earlier field keeps its name and meaning, and the
status plugin makes no network call. The MCPget_statustool doesn't carry the dates: on a
server with several hundred sources they made its answer too large (see v0.4.10). - A check for newer publisher files.
node dist/fetch/freshness-cli.js --targets FILEasks
whether publishers have released newer files than the ones you loaded. It downloads nothing.
Each archive gets one HEAD request and each listing page one read of at most 2 MiB, under the
usual robots, terms and pacing rules.--planprints what it would check and sends nothing.
A target answersbehind: yesornoonly when both sides are known, andunknown
otherwise. A host that is held, has no current terms review or would run past its request cap
getsunknownwithout a request. A listing target can name the years it serves. Files for
other years are counted as out of scope and not compared, so an older year never reads as
behind.src/fetch/README.mddescribes the targets file.
Changed
- The shipped access manifest lists the Medicare plan archives on www.cms.gov and the Part D
archives on data.cms.gov, with their listing pages, so the freshness check can reach them.
Collecting those files still takes an operator manifest entry.
Fixes
- Provider searches use the search keys when operator geocoder points exist. In v0.4.8 any
operator point sent every radius search back to the original path. Now only the identities an
operator point touches are read from the corrected points, and every other identity comes from
the keys. Answers don't change. - Census downloads work again with the shipped access manifest. The Census copyright page the
manifest pins changed its bytes on 2026-11-13, so every www2.census.gov collection stopped on a
terms mismatch. A review on 2026-11-14 found the same permitted use, and the manifest now pins
the new hash. - Medicare release imports no longer record the download day as the publisher's date. When a
release file's name has no date and the server sends noLast-Modified, the import now stores
no publisher date. Before, it stored the day OpenPlans fetched the file. Snapshots imported
earlier keep their stored value, and the status page shows their publisher date as unknown.
Development
scripts/ci.shbuilds the SDK, the plugins and the app once, before its checks, where it used
to build them three times. Vitest now runs test files in parallel: a third of the CPUs, at most
3 workers, and one file at a time on a machine with fewer than 6 CPUs. Set
OPENPLANS_TEST_WORKERS=<n>to choose the count.scripts/postgis-tests.shstill runs its
files one at a time, because they share one database server.- Tests and plugin tests no longer use
any. ESLint now checks theno-unsafe-*rules there
with type information too, as it already did forsrc/. fetchTransienttakesheadOnly: true. It sends the data request as HEAD, reads no body and
returns the publisher'sLast-Modified,ETag,Content-LengthandContent-Type.docs/mcp-tools.jsonlists every MCP tool with its title, its description, whether it is core
or comes from a plugin, and when it is listed.npm run mcp:manifestrebuilds it from the
code, and a test fails when the committed file no longer matches.- CI tests each commit once. A push to
mainof a commit that already passed ondevelopskips
the check jobs and links that run, and tag pushes start no run. Everything else, pull requests
included, still runs every check.
Upgrading
- Pull the new image. There is no migration to run. The provider search keys from the v0.4.8
backfill serve the new paths as they are. Run the backfill again only after an NPPES or geocode
load, as before. - The status plugin moves from 0.1.2 to 0.1.3, so its package hash changes. If you keep an
approved plugin list, start the new image on the side, read the plugin's version andsha256
from/status/operator.jsonas in the release preflight indocs/plugins-operations.md, and
replace the old entry. - The other bundled plugins keep their v0.4.8 versions and package hashes.
OpenPlans v0.4.8
This release makes nearby-provider searches answer within the request limit on a database with
providers from every state. A new worker command, worker backfill provider-search, builds search
keys from the NPPES identities and their geocoded points. A radius search then reads only the
area around its origin instead of providers spread across every loaded state.
It has three migrations, 1007 to 1009, which add new empty tables and their indexes, and one
backfill to run after migrating. See Upgrading below. Search results, totals and counts don't
change. One answer does: when the count of addresses without a located point can't finish in
time, the search answers 200 and marks that count unknown. It used to answer 504. The bundled
plugins keep their v0.4.7 versions and package hashes.
What users notice
- Provider searches in busy areas answer in time. A nearby-provider search for a common name
such as SMITH, for a taxonomy code, or with no filter used to read identities and points in
every loaded state. With a nationwide NPPES load it ran past the 5-second limit and answered 504
query_timeout. After the backfill, the search reads the keys for the 0.1-degree grid cells
around its origin, applies the same filters and distance test, and reads full records only for
the providers on its page. The unlocated count comes from the same keys. Results, totals and
counts match the original path. - The keys are used only while they match the provider tables. After an NPPES or geocode load,
searches take the original path until the backfill runs again.
Changed
- An unlocated count that can't finish answers 200, not 504. Without current search keys, a
radius search counts the practice addresses that have no located point, and that count has a
two-minute limit of its own. When the search can't wait for it, the search now answers with its
results,meta.unlocated: nullandmeta.unlocated_status: "unknown". In v0.4.6 and v0.4.7 it
answered 504query_timeout. The response cache doesn't keep such an answer. A count that runs
past its limit isn't started again for ten minutes, and searches in that time answer it as
unknown. The compatibility API addsprovider_unlocated_count_unknownto its gaps header, and
the MCPsearch_providerstool returnsunlocated: nullwithunlocated_status: "unknown". - MCP
search_providerssays what its unlocated count means. It now returns
unlocated_statusnext tounlocated:countedwhenunlocatedis the exact count,unknown
when the count didn't finish in time and some candidate addresses may have no location, and
not_applicablefor an NPI lookup. Before, anullcount could mean either of the last two. worker migrateandworker migrate --checkrefuse while a provider-search backfill runs, and
the backfill refuses while a migration runs.
Fixes
- Background unlocated counts no longer crowd out requests. When the provider search keys
are stale, at most one exact unlocated count runs at a time, on its own database connection
outside the request pool. Counts and the ten-minute pause after a timed-out count follow the
provider tables' revisions, so plan catalog writes no longer restart them. scripts/smoke.shpasses on a default setup again. Household quotes are open without a token
by default, but the smoke script still expected a 503 and failed unless you set
OPENPLANS_PUBLIC_HOUSEHOLD=offyourself. It now checks the open default, then restarts the API
withOPENPLANS_PUBLIC_HOUSEHOLD=offand checks the refusal. It builds its images under tags
unique to the run and removes them afterwards, so two runs on one Docker host no longer replace
each other's images. The newOPENPLANS_DB_IMAGEsetting picks the Compose database image. Its
default,openplans-db:local, is unchanged.- The backup commands in the docs no longer start the API. They now run the worker with
--no-deps, so a restore doesn't start the API early. - The docs match the code. The API guide lists every route, including
/v1/cache-stats,
/healthzand/readyz, and has an error table. The configuration guide lists every config
file key.
Development
- Code under
src/andplugins/*/src/no longer usesany. ESLint checks theno-unsafe-*
rules there with type information. - A test checks the docs against the routes, MCP tools, environment variables, config file keys,
the Node.js version and every relative link. - A test runs the smoke script's household checks against the app on an empty database, so CI
notices when they drift from the server's defaults. - Release validation runs its Linux checks in a container image pinned by digest.
scripts/postgis-tests.shruns every suite that needs PostGIS, including the comparison of
keyed and original provider searches, in a disposable database container. It fails when one of
those tests is skipped. A new CI job runs it.
Upgrading
- Pull the new image and run the migrations. Migration 1007 adds three empty tables:
provider_search_key_a,provider_search_key_bandprovider_search_build. Migrations 1008
and 1009 each build one index withCREATE INDEX CONCURRENTLY. The tables are still empty, so
the builds take well under a second, and the old version keeps serving. Older versions never
read the new tables. If a build fails, it leaves an invalid index. Drop it with
DROP INDEX CONCURRENTLY provider_search_key_a_cell;orprovider_search_key_b_cell, then
run the migrations again. - Once the migrations have finished, run the backfill once:
docker compose run --rm worker backfill provider-search --free-gb N, where N is the free space
in GB on the database's disk, or--disk PATHwith a directory on that disk. It refuses below
8 GB, and it refuses whileworker migrateruns. It reads every practice address and point once
and fills a second copy of the keys while searches keep reading the first, then switches. With a
nationwide provider load it takes minutes. Until it finishes, searches take the original path,
as in v0.4.7, and answer the same. - Run the backfill again after every NPPES or geocode load.
- If you stop a backfill, check that its
INSERThas stopped on the database server, and cancel
it withpg_cancel_backendif not, before you start the backfill again. - The bundled plugins keep their v0.4.7 versions and package hashes, so an approved plugin list
needs no change.
OpenPlans v0.4.7
This release makes the status page shorter and cuts the database queries behind pricing and
plan searches. /status groups its snapshots by source, counts DC apart from the states, and
links to plans.openhra.com. Pricing requests and plan searches read the rows for all their plans
in one query instead of one plan at a time.
It also updates Node.js to 22.23.5. It has no migrations and no backfill. See
Upgrading. Prices and plan details in API answers don't change. One provenance list
now keeps a fixed order, as Changed below explains. /status.json and the get_status tool don't
change. The status plugin moves to 0.1.2, so an approved plugin list needs its new hash.
Security
- Node.js runtime updated to 22.23.5 (security release). The Dockerfiles now pin their base images
by digest.
What users notice
- A shorter status page.
/statusgroups active snapshots by source. Each source gets one
line with its snapshot count and ages, and its snapshots sit in a<details>element you can
open. The page used to list every snapshot in one long table. It now says "48 states and DC"
where it said "49 states", and it links to plans.openhra.com./status.jsonand the
get_statustool don't change, and theirdata.statesstill counts DC as one place.
Changed
- Benchmark and estimate responses now list the provenance of pediatric dental benefit rows in
source-row order. Before, that order could vary between data loads.
Fixes
- Pricing and plan requests run a fixed number of queries. Quotes, premium estimates, the
silver benchmark, ICHRA affordability checks, native plan search and compatibility medical
searches used to read rate rows, plan attributes, cost sharing and lookups such as the rating
rule once for every plan. A benchmark for a household with children read child dental benefits
and dental rates plan by plan too. Each request now reads the lookups once and the rows for all
its plans in one query, so the number of queries no longer grows with the number of plans in a
county. With 40 extra plans in a test county, an ICHRA check went from 850 queries to 11, the
silver benchmark from 307 to 9, native plan search from 166 to 19 and compatibility search from
1,221 to 22. The count stays fixed when plans have a crosswalk, the mapping from last year's
plans. Each request reads every plan's prior-year IDs in one query, so with a crosswalk native
plan search runs 20 queries and compatibility search 23. Requests that name plans by variant ID
check all the IDs in one query. Prices and plan details don't change.
Upgrading
- Pull the new image. There is no migration to run and no backfill.
- The status plugin moves from 0.1.1 to 0.1.2, so its package hash changes. If you keep an
approved plugin list, start the new image on the side, read the plugin's version andsha256
from/status/operator.jsonas in the release preflight indocs/plugins-operations.md, and
replace the old entry. - The other bundled plugins keep their v0.4.6 versions and package hashes.
OpenPlans v0.4.6
This release adds a readiness check and makes provider searches faster. While migrations are
pending, /readyz and the data routes answer 503 schema_not_ready instead of failing with a
500, and /healthz stays a liveness check. When a read runs past its timeout, the API now
cancels it on the database server and answers 504 query_timeout instead of 500. The PGlite
developer server won't start on a database with unapplied migrations.
It has one migration, 1006, which builds an index concurrently, so the old version keeps serving
while it runs. There is no backfill. See Upgrading. Search results, totals and
counts don't change. Status codes change in two places: a read that times out answers 504, and
pending migrations answer 503. Both used to answer 500.
What users notice
- A readiness check.
GET /readyzanswers 200{"status":"ready"}once the database answers
and every migration is applied, core and enabled plugins alike. Until then it answers 503 with
reason: "schema_not_ready"and the number ofpendingfiles. A down database gives
db_down, and a journal that can't be read givesschema_unknown. - Pending migrations answer 503, not 500. While a migration is pending, the native and
compatibility routes answer 503 with the codeschema_not_readyand aRetry-Afterheader.
MCP answers 503 with a JSON-RPC error whosedata.reasonisschema_not_ready. The/status
pages keep answering. The API reads the migration journal at most once
every 5 seconds, so it starts serving a few seconds after the migration finishes, with no
restart. /healthzis a liveness check. It still answers 200 while the process and its database
connection are up. While migrations are pending, its body adds"schema":"not_ready"and the
pendingcount. A Compose health check on/healthzbehaves as before, so the worker can still
start and migrate.
Fixes
- Timed-out reads stop on the server. The database client's read timeout only stopped
waiting, so a slow query kept running after its request had failed. When a read passes its
5-second timeout, the API now cancels the statement through its separate cancellation
connection and waits for the connection to answer before reusing it. If the cancellation fails,
the API discards the connection. The caller gets a 504query_timeout, described below. - The PGlite server refuses an unmigrated database.
npm run api:pgliteused to start on a
new database, and then every data route failed with a 500. It now exits and names
npm run api:pglite -- migrate. - Faster provider searches. A name search that matches up to 1,000 providers now starts from
those providers and checks their distance with a new covering index (migration 1006). It used
to scan every point in the radius. A common name keeps the radius scan but drops points of
other providers early. An exact taxonomy code finds its providers through the code index. The
API keeps the exact count of unlocated addresses per data generation and filter set, so a
repeat search doesn't count them again. Results, totals and counts are the same as before. - A read that times out answers 504. A read that runs past its 5-second limit now answers
HTTP 504{"error":{"code":"query_timeout"}}on the native and compatibility APIs. It used to
answer 500INTERNAL_ERROR. MCP tools answer the codequery_timeoutwithretryable: true.
When the unlocated count can't finish in time, the search answers 504 and the count keeps
running, up to two minutes. The next search with the same filters then reads it. - Pricing requests read the county catalog once. Quotes, premium estimates, the silver
benchmark, ICHRA affordability checks and compatibility medical searches used to read the
county's whole plan catalog again for every plan they priced, so counties with many plans were
slow. Each request now reads the catalog once. Answers don't change.
Development
- A geography test helper moves from
src/totests/, next to its only test. The build no
longer compiles it intodist/, so the image no longer carries it. - Ingest code opens downloaded files only through the snapshot store. A test fails when code
undersrc/ingestorsrc/workerbuilds araw/path itself.
Upgrading
- Pull the new image and run the migrations. Migration 1006 builds one index on
address_point
withCREATE INDEX CONCURRENTLY, so the old version keeps serving while it builds. On a large
provider load the build can take several minutes, and/readyzanswers 503
schema_not_readyuntil it finishes. If the build fails, it leaves an invalid index. Drop it
withDROP INDEX CONCURRENTLY address_point_npi_coordinates;and run the migrations again.
There is no backfill. - The Compose database profile now sets
random_page_cost=1.1and
effective_io_concurrency=200. They take effect when the db container is recreated. - Point readiness probes, load balancers and deploy checks at
/readyz, and keep/healthzfor
liveness. A 200 from/healthzno longer means the schema is current. - The bundled plugins keep their v0.4.5 versions and package hashes, so an approved plugin list
needs no change.
OpenPlans v0.4.5
OpenPlans v0.4.5
This release gives a reason where provider and drug searches, and MCP coverage, network and quote
records, answered unknown or an empty list without one. MCP errors that the HTTP transport sends
after reading a request now carry the request's id.
It has no migrations and no backfill. See Upgrading. Answers change only where they
used to be unknown or empty without a reason. The MCP output schema changes for
search_providers.
Fixes
- Coverage and network answers keep their reason over MCP. When
check_drug_coverage,
check_provider_networkorquote_plansanswersunknown, the record'sgapsnow holds the
native reason, such assource_set_not_available. Before, only answers from the CMS fallback
carried it. - Empty provider searches say when no registry is loaded.
GET /v1/providersanswers an empty
identity search withstatus: "unknown"andreason: "provider_registry_not_loaded"when no
NPPES release covers the ZIP's state. The MCP toolsearch_providersadds the samereason
(null otherwise), and the compatibility provider search adds it tox-openplans-gaps. - Drug search says when terminology is missing.
GET /v1/drugsaddsterminology_status.
With no RxNorm release loaded it isunknown, withreason: "rxnorm_terminology_unavailable".
An empty list withavailablemeans no concept matched. - MCP transport errors carry the request id. The MCP HTTP transport's own errors always
carried"id": null, though JSON-RPC 2.0 asks for the request's id whenever the server can read
it. Once the body parses as a single request, these errors now carry its string or number id: a
missingMCP-Protocol-Versionheader, the personalized and estimate access errors,
AUTH_NOT_CONFIGURED, the concurrency limit and the deadline error. Errors sent before the body
is parsed keepnull: the Origin and Host checks, the method check, the rate limit, content
type, size limit and parse errors. So do batches, notifications and requests with a malformed
id.
Development
scripts/oracle/surface-sweep.mjsalso sweeps what loads beside the catalog: provider searches
for every ZIP, sampled NPPES identities, directory listings and formulary drugs against provider
detail, participation, drug search and coverage, and Medicare plan detail routes. Unknown records
inside an answer need their own reason. Seescripts/oracle/README.md.- The test toolchain moves to Vitest 5.0.5, with Vite 8.3.5 as a dev dependency.
Upgrading
- Pull the new image. There is no migration to run and no backfill.
- If you validate MCP output against its schema, take the new schema from
tools/list.
search_providersgains a nullablereason. Clients ofGET /v1/drugssee the new
terminology_statusfield, and clients ofGET /v1/providersmay getstatus: "unknown"with
provider_registry_not_loadedwhere they used to get an empty list. - The bundled plugins keep their v0.4.4 versions and package hashes, so an approved plugin list
needs no change.
OpenPlans v0.4.4
OpenPlans v0.4.4
This release moves the web framework dependencies to patched versions. It fixes MCP tools that
answered territory ZIPs and Vermont ICHRA checks with an internal error, and gives a reason where
a county or Medicare search used to come back empty without one. The last config-file keys that
OpenPlans accepted but never read now take effect.
It has no migrations and no backfill. See Upgrading. Answers change only where
they used to be an internal error or an empty list without a reason. The MCP output schemas
change for search_medicare_plans and check_ichra_affordability.
Security
- Security: updated the web framework dependencies (hono, @hono/node-server) to patched versions.
What users notice
- Unloaded states and years say so. A county whose state has no active catalog for the
requested year, such as a state the service has not loaded or a plan year it does not hold, now
getsstate_catalog_not_loadedinissues,location_issuesandx-openplans-gapsinstead of
an empty list with no reason. - Medicare search names its reason. The MCP tool
search_medicare_plansaddsreason, the
same codeGET /v1/medicare/plansgives, such ascatalog_not_loadedwhen no Medicare catalog
is loaded. It is null otherwise. - Medicare search for an unknown ZIP.
GET /v1/medicare/plansandsearch_medicare_plans
give reasonzip_not_in_loaded_geographyfor a ZIP outside the loaded geography.
Fixes
- MCP
lookup_geography,search_plansand the other tools that list counties answered a
Puerto Rico, Guam or other territory ZIP with an internal error, because a territory county has
no state code. Such a county now carries its territory code (PR,GU,VI,AS,MP). - MCP
check_ichra_affordabilityanswered every Vermont county with an internal error. The
output check wanted HIOS plan IDs and an age, but a Vermont LCSP is a filed plan key and
community rating has no age.lcsps[].plan_idsnow takes plan keys too, and
identified_at_ageandpriced_at_agemay be null.
Self-hosting and operations
- The remaining config-file keys take effect. The file can now set the database URL
(db.connectionString), the response cache switch (cache.enabled), the public access
switches (public.quoting,public.household,public.compat), the API and compatibility
tokens (tokens.api,tokens.compatKey,tokens.compatKeyHeader), the trusted proxies
(trustProxy), the operator manifest (access.operatorManifest) and the project URL
(access.projectUrl). Before, the file accepted these keys and every reader ignored them.
An environment variable that is set still wins over the file. The compatibility routes now read
their key and header name once, when the API starts. Seedocs/configuration.md.
Development
scripts/oracle/build-price-check-db.shbuilds the Part D price check database from cached
CMS files. It cuts the quarterly archive down to the sample's plans and loads it with the
application's own importers.scripts/realdata.sh --with-price-checkbuilds it and then runs
the check. Seescripts/oracle/README.md.scripts/oracle/surface-sweep.mjscalls every public read route and MCP tool for every county
of each loaded state and plan year, by county and by ZIP. A response fails on a 5xx, on
INTERNAL_HONESTY_CHECK, or on an empty answer that names no reason.scripts/realdata.sh
runs it whenOPENPLANS_SURFACE_SWEEP_DATABASE_URLnames a loaded database.
Upgrading
- Pull the new image. There is no migration to run and no backfill.
- If you validate MCP output against its schema, take the new schemas from
tools/list.
search_medicare_plansgains a nullablereasonfield. Incheck_ichra_affordability, the
plan_idslists underlcsps[]and itsby_basispicks accept state plan keys as well as
HIOS IDs, andidentified_at_ageandpriced_at_agemay be null. Clients that parseissuesor
location_issuesseestate_catalog_not_loadedfor more counties. - Each bundled plugin now names the new hono version as its peer dependency, so each one has a
new patch version and a new package hash. The status, webhook, template, S3 blob store and
both source plugins move from 0.1.0 to 0.1.1, and Slack moves from 0.2.0 to 0.2.1. Their code
and messages do not change. If you keep an approved plugin list, start the new image on the
side, read each entry's version andsha256from/status/operator.jsonas in the release
preflight indocs/plugins-operations.md, and replace the old entries. "Upgrade to Slack
0.2.0" there gives the Slack 0.2.1 entry. - Check your config file before upgrading. Keys from the list above that it already holds now
take effect. For example,tokens.compatKeyin the file now guards the compatibility routes,
and apublic.*switch set tofalseturns that access off. Without a config file nothing
changes.
OpenPlans v0.4.3
OpenPlans v0.4.3
This release prices Part D drugs selected for Medicare price negotiation from their CMS maximum
fair price, and keeps cached API answers valid while Part D prices load in small batches. Prices
stay behind the Part D pricing setting, which is off by default. Plan lists and quotes now say
why plans were left out, and config-file switches now take effect.
It has one migration (1005), which changes triggers on the three Part D price tables, and no
backfill. See Upgrading. Plan search and quote responses gain reason fields, and
two subsidy reasons get more specific codes. Statuses, prices and benchmarks stay the same on a
service that keeps OPENPLANS_MEDICARE_DRUG_COST_PRICES off. A config file that sets a key read
only from the environment now stops startup.
What users notice
- Maximum fair prices for selected drugs. With
OPENPLANS_MEDICARE_DRUG_COST_PRICESon, a
drug selected for the Medicare Drug Price Negotiation Program is priced from its maximum fair
price instead of the plan's average unit cost. The estimator takes the price per unit in effect
on the fill date from the CMS Selected Drug List and Maximum Fair Price file, multiplies it by
the quantity, and adds the lowest and the highest selected-drug dispensing fee. When both fees
give the same cents, the gross cost is avalue; otherwise it isbounded. CMS prices its
worked example at exactly the maximum fair price plus the fee, and the estimator does the same.
The answer says so in its assumptions. A selected drug with no price in effect on the fill date
answersunknownwithmaximum_fair_price_not_in_effect, and the plan average is never used in
its place. When the formulary flag and the CMS list disagree, the estimator counts both ways and
gives a gross cost only when they agree to the cent. Otherwise it answersunknownwith
maximum_fair_price_may_apply. Thepriceblock gainsingredient, the per-unit price with
its effective dates, and amaximum_fair_price_totalfigure, which other drugs report as
unknownwithdrug_not_selected. The MCP output schema lists the new fields.
data/medicare-part-d/drug-lists.jsonpins the CMS file and holds its prices for 2026 and 2027.
Seedocs/medicare.md. - CMS worked examples priced exactly. Five CMS worked examples use selected drugs: C7
examples 1, 3, 4 and 5, and C12 example 1. Withprice_basis: "cms_plan_average"they are now
priced from the maximum fair price, and every figure matches CMS to the cent over HTTP and MCP.
C7 example 4 is no longer a range. C12 example 1 could not be reproduced from plan averages
and now can. The independent price reference
script reads the same CMS file with--mfp-fileand reportsmaximum_fair_price_total. - Plan lists say why they may be short.
GET /v1/plansandPOST /v1/quotesadd
issues, and the MCP toolssearch_plansandquote_plansaddlocation_issues. Each lists
reason codes:zip_limited_service_areawhen a county-only request leaves out plans that serve
part of the county,zip_not_in_loaded_geography,state_catalog_not_loaded, and the New York
template refusal code, such astemplate_saved_before_submission, when a refused issuer's plans
are missing from the region. The list is empty when no plan is known to be missing. - Subsidy reasons name the gap. A subsidy for a ZIP outside the loaded geography now has
reasonzip_not_in_loaded_geographyinstead ofunknown. A New York or Vermont county without
its state catalog has reasonstate_catalog_not_loadedinstead ofunsupported_rating_method.
Statuses do not change. - Compatibility gaps. Medical and dental search add the same codes to
x-openplans-gaps. The
compatibility README lists the mapping.
Self-hosting and operations
- Cached answers stay valid during a staged Part D price load. Staged unit-cost and
dispensing-fee batches used to move the API data generation, so the response cache recomputed
every answer for the whole load. From migration 1005, writes topartd_plan_unit_cost,
partd_pricing_releaseandpartd_dispensing_fee_rangemove the generation only when a row
belongs to a release that lists the table. Listing the tables, or withdrawing them after a
failed check, moves it once. TRUNCATE still always moves it.checkCatalogTriggersreports a
missing or disabled trigger on these tables. Seesrc/api/cache/README.md. - Hosted release process. The hosted service's release tool now runs scripted public checks
after each release and records them in its receipt. The checks cover the reason fields added
in this release. A read-only checker reports whether the service is ready for a blue/green
release. These tools are not part of this repository. - Config-file switches take effect. The config file keys for the Medicare switches
(medicarePartD,medicareDrugCost,medicareDrugCostPrices), Georgia quote recovery
(gaQuoteRecovery), the compatibility options (compat.catastrophicAgeRule,
compat.benefitText) andcmsFallback.quotesused to be accepted and then ignored. They now
work. An environment variable that is set still wins over the file. With neither set, every
switch stays off. - Environment-only keys refused in the file. Settings that programs read straight from the
environment can no longer go in the config file:compose.*,geocoder.*,runners.*,
cmsFallback.apiKeyandaccess.egressFile/access.egressSha256. A file that sets one
stops the API, worker, stdio server and PGlite runner at startup with one line naming the
variable to set instead. See "Environment-only settings" indocs/configuration.md. - Data directory and egress country in the config file.
access.dataDirand
access.egressCountrynow reach every reader: the API, the worker, the import runners and the
state check scripts. Each takes the environment variable first, then the file, then the
default.access.dataDiralso sets the root of thelocalblob store unless the file sets
blobs.root.scripts/smoke.shandsrc/ingest/geocode/geocoder.shstill read only
OPENPLANS_DATA_DIR. - Slack plugin 0.2.0 posts rollbacks. The Slack plugin posts
release.rolled_backas a
warning, for exampleOpenPlans: Release rolled back from 1.4.0 to 1.3.2.It names the two
versions and never the image ID. Without aneventsoption it posts rollbacks as soon as 0.2.0
loads. With aneventslist, add"release.rolled_back"to get them. WithminSeverityset
toerror, rollbacks are dropped. See "Upgrade to Slack 0.2.0" in
docs/plugins-operations.md.
Fixes
- The macOS CI checks run as three shards on separate runners. One macOS job ran past its
60-minute limit, because the suite runs one file at a time and those runners take about
twice as long as Linux.scripts/ci.shruns one slice of the tests when
OPENPLANS_CI_SHARDis set. TheOpenPlans / macOScheck now passes only when every shard
passed. - The plugin guide example test gives its nested test run an explicit timeout. On a hosted macOS
runner, loading the example plugin with a fresh database took longer than vitest's 5-second
default. - MCP
search_plansanswered a New York county with an internal error, because a filed plan
keyed by its HIOS ID did not match the state plan-key pattern. Such a plan is now returned as a
HIOS plan.
Docs
docs/medicare.mdnow lists the estimate statuses, the maximum fair price reasons and the
price check as the code has them.docs/ichra.mdcovers the PY2025 look-back, the reasons a quote asks for a ZIP, and the New
York rate source override.docs/configuration.mdlists every switch with its config key and environment variable.
.env.examplelists the two drug-cost switches.- The API README describes the
zip_not_in_loaded_geographyandstate_catalog_not_loaded
benchmark reasons.docs/migrations.mdcounts migrations through 1005, and the plugin docs
describerelease.rolled_back.
Development
- The Part D price check no longer compares the member cost for a selected drug with no maximum
fair price in effect, since the independent reference stops before cost sharing there. - Tests that plant mutated source files write each one into a fresh temporary folder, so test
runs that share a checkout no longer overwrite each other's copies. - The checks that run before a change merges now also check the wording of every file published
in this repository.
Upgrading
- Pull the new image and run
worker migrate. Migration 1005 adds two functions and swaps the
data-generation triggers on the three Part D price tables. It creates no table and adds no
rows. The tables only take writes during a Part D price import, and are empty until the first
one. worker migrate --checkclasses 1005 asrisky, because the classifier has no rule that
clears a dropped trigger. The section on 1005 indocs/migrations.mdexplains the locks it
takes. A release runner that refuses risky files needs
--allow-risky-migration 1005_partd_staged_generation.sql. Apply it before any Part D price
load. Images from v0.4.2 keep working on the new schema.- No backfill is needed.
- If you run the Slack plugin, replace its approved-list entry with version
0.2.0and the
sha256 given in "Upgrade to Slack 0.2.0" indocs/plugins-operations.md. Version 0.1.0 refuses
"release.rolled_back"inevents, so change that list only together with the upgrade. - If you parse plan search or quote responses, expect the new
issuesfield on REST and
location_issueson MCP, and the two new subsidy reason codes. The compatibility search adds
the codes tox-openplans-gaps. - Check your config file before upgrading. If it sets
compose.*,geocoder.*,runners.*,
cmsFallback.apiKey,access.egressFileoraccess.egressSha256, move the v...
OpenPlans v0.4.2
OpenPlans v0.4.2
This release asks for a ZIP when a part-county dental plan would set a county-only benchmark,
adds an optional New York rate source for issuers whose template was refused, and adds the first
Part D drug pricing pieces: dispensing-fee ranges, a unit-cost reader and bounded fill pricing.
The pricing pieces are off by default. It also adds the release.rolled_back plugin event.
It has two additive migrations (1003 and 1004) and no backfill. See Upgrading.
One kind of answer changes: requests for a ZIP outside the loaded geography, such as New York
and Vermont ZIPs on a service with a CMS key, used to fail with a server error and now answer
unknown or unsupported_rating_method with a reason (see Fixes). The new dental
answer applies only where a part-county dental plan would have set the benchmark, and the New
York and Part D pricing changes stay off until an operator turns them on.
What users notice
- County-only quotes with part-county dental plans. For a household with a child under 19,
the benchmark adds the pediatric dental adjustment. Without a ZIP, that step used to drop
stand-alone dental plans that serve only part of the county, so the benchmark could use the
wrong dental premium. Such a quote now returnslocation_requires_zipwith reason
zip_limited_service_area, the same answer as for part-county silver plans, and the credit
and net premium arenulluntil you send a ZIP. Quotes with a ZIP, adult-only households and
counties without such plans do not change. In the current catalog no answer changes. - Plan-average drug prices in Part D estimates. A new setting,
OPENPLANS_MEDICARE_DRUG_COST_PRICES, lets drug-cost estimates accept
price_basis: "cms_plan_average". It is off by default and counts only while the estimator is
on. With it on, each fill is priced from the plan's average unit cost and the lowest and highest
dispensing fee, and a figure is avalue,boundedorunknown. Aboundedfigure has
cents: nullwithminimum_centsandmaximum_cents, and the answer never picks one amount
inside the range. Each priced fill carries apriceblock that cites its pricing row and fee range. A
release without pricing rows or fee ranges answersunknownwithpricing_not_loadedor
dispensing_fees_not_loaded./v1/data-availabilitysays whether prices are loaded and the
setting is on, and lists the basis only when both hold. The HTTP route and the MCP tool return
the same answer, and the MCP output schema now accepts bounded figures. If you parse estimate
figures, handle theboundedstatus.docs/medicare.mdexplains how prices are read and what
stays unknown.
Self-hosting and operations
- Optional New York rate source. When the New York template check refuses an issuer's DFS
approved-rates template, that issuer's NY rates stayunknown. A new config file entry,
ny.rateSourceOverrides, can name the issuer and take its family-tier rates from the CMS
state-based exchange rate file instead. Each rate cites the publication, the file member and
its CSV row. Preparation and import refuse the override unless that issuer's template was
refused, and unless the CMS file agrees to the cent with every DFS approved rate it lists for
other issuers. Plans with no row in that file stayunknown. It is off by default, and turning
it on is your decision. With it off the NY artifact is byte-identical. See
docs/configuration.md. - Part D dispensing-fee ranges.
worker ingest medicare part-d import --tables dispensing_feereads the pharmacy networks
file and stores, per plan, channel, in-area flag, fee type and days supply, the lowest and
highest fee, how many pharmacies list a fee or show., and the highest floor price. It keeps
no pharmacy rows, and.counts as missing, never as zero. The importer accepts both spellings of the selected-drug fee header, and it can now add a
large table to a release that is already loaded. - Part D unit costs in a compact table. Plan average unit costs now go into
partd_plan_unit_cost(migration 1004), whose rows carry a two-byte release key in place of
the snapshot id. Answers still name the full snapshot. Pricing imported before 1004 reads as
not loaded; import it again with--tables pricing. - Part D fill pricing with bounds. A reader returns a plan's unit cost only for an exact row
(30, 60 or 90 days at retail), andunknownwith a reason otherwise. The estimate engine can
price a fill from that unit cost and the lowest and highest dispensing fee. When the fee range
moves the result, the answer gives the gross cost, patient pay and TrOOP increment as a range.
Missing fees, floors that could bind and missing prices stayunknown. The new
OPENPLANS_MEDICARE_DRUG_COST_PRICESsetting, described above, turns it on. - New event
release.rolled_back. The plugin event catalog gainsrelease.rolled_back
(version,imageId,fromVersion), emitted after a hard-release rollback. The webhook plugin
posts it when itseventslist names it. The Slack plugin does not post it. - Hosted release process. The hosted service's release tooling gained a blue/green mode with
a time limit on checks after a switch, recorded rollbacks and a fix for a rollback that held
the release lock. It can also add states to a plan year that is already served, and a load that
fails a later check is taken out of service again. These tools are not part of this repository. - Part D prices load in small batches. The importer can stage the unit-cost and
dispensing-fee rows of an imported quarterly release in transactions of a few thousand rows,
without listing them for the release, and a rerun resumes from the rows already stored. The
one-transaction import refuses to add a table that is staged. - Hosted Part D price load. The hosted release tool gained an optional
--load-partd-prices <year>step. It needs a free-disk margin before it starts, loads the price
and dispensing-fee data in small batches, and keeps the data unserved until row counts and
checksums match the reviewed release. A failed check takes the data back out of service. The
step does not turn on the price basis. - Part D price check in the real-data script.
scripts/realdata.shnow checks 2026
plan-average prices against its own reading of the cached quarterly archive when
OPENPLANS_PRICE_CHECK_DATABASE_URLnames a database with that release's pricing and
dispensing-fee tables. Without one, the step printsSKIP. The C7 and C12 CMS worked examples
also run over HTTP and MCP through plan-average prices.
Fixes
- No more server errors for unloaded ZIPs. Request routes read the database in a read-only
transaction. For a ZIP outside the loaded geography, the CMS county lookup tried to reserve
its daily budget and record the attempt, Postgres refused both writes, and/v1/benchmark,
the quote and premium-quote routes and the MCP search and quote tools returned
INTERNAL_ERROR. This happened whenever a CMS key was set. In a read-only request the lookup
now uses cached rows only. The benchmark then answersunknownwith
zip_not_in_loaded_geography. New York and Vermont rates come from a state catalog. When
none is loaded for the year, they answerunsupported_rating_methodwith
state_catalog_not_loaded. - The macOS CI job gets 60 minutes. A run hit the 45-minute limit.
- The MCP tools-list negative controls give each mutated server its own file name, so two test
runs in one checkout no longer load each other's half-written copy.
Upgrading
- Pull the new image and run
worker migrate. Migrations 1003 (the dispensing-fee range table)
and 1004 (the release key and keyed unit-cost tables) create new empty tables and add a few
literal metadata rows. They are additive and passmigrate --checkwhen size evidence shows
the metadata tables are small. - No backfill is needed. If you imported Part D pricing before, import it again with
worker ingest medicare part-d import --kind quarterly --tables pricingif you want unit costs
available to the reader. partd_unit_costfrom migration 950 is no longer read or written. A later migration drops it.