Skip to content

Releases

v0.4.11

Choose a tag to compare

@openhra openhra released this 16 Nov 18:09

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_status returns aggregate counts by default and stays below 64 KiB. Use section,
    offset and limit for paged details. Oversized rows are omitted and counted, with
    truncated: true. Paged source details include published_at and published_from; the
    summary keeps aggregate counts. REST status responses keep their existing shape.
  • Opt-in GET /v1/lowest-premiums and MCP get_lowest_premiums find 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-msot resolves an operator's custom_payment_allowed flag beside
    public plan facts through /msot/resolve and MCP msot_resolve. It requires a reviewed inline
    source. Missing evidence stays unknown; the flag does not establish insurer payment acceptance.
  • Optional @openplans/plugin-admin adds 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 migrate before starting the new API. Migration 995_handy_lowest.sql adds 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-status from 0.1.4 to 0.1.6 with the
    rebuilt package hash. Read the version and sha256 from the new image's
    /status/operator.json, as in docs/plugins-operations.md, before replacing the entry.
  • OPENPLANS_LOWEST_PREMIUMS stays off unless set to on. The new @openplans/plugin-msot
    and @openplans/plugin-admin packages 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

Choose a tag to compare

@openhra openhra released this 15 Nov 04:42

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_status tool 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_status with RESULT_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.json and the status page still show published_at and published_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/providers answers in time.

OpenPlans v0.4.9

Choose a tag to compare

@openhra openhra released this 15 Nov 04:42

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, /status split 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-Modified date. /status.json and /status/operator.json add two fields per source:
    published_at (YYYY-MM-DD) and published_from (release_date or last_modified). Both
    are null when the date is unknown. Every earlier field keeps its name and meaning, and the
    status plugin makes no network call. The MCP get_status tool 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 FILE asks
    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. --plan prints what it would check and sends nothing.
    A target answers behind: yes or no only when both sides are known, and unknown
    otherwise. A host that is held, has no current terms review or would run past its request cap
    gets unknown without 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.md describes 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 no Last-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.sh builds 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.sh still runs its
    files one at a time, because they share one database server.
  • Tests and plugin tests no longer use any. ESLint now checks the no-unsafe-* rules there
    with type information too, as it already did for src/.
  • fetchTransient takes headOnly: true. It sends the data request as HEAD, reads no body and
    returns the publisher's Last-Modified, ETag, Content-Length and Content-Type.
  • docs/mcp-tools.json lists 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:manifest rebuilds it from the
    code, and a test fails when the committed file no longer matches.
  • CI tests each commit once. A push to main of a commit that already passed on develop skips
    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 and sha256
    from /status/operator.json as in the release preflight in docs/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

Choose a tag to compare

@openhra openhra released this 14 Nov 17:36

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: null and meta.unlocated_status: "unknown". In v0.4.6 and v0.4.7 it
    answered 504 query_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 adds provider_unlocated_count_unknown to its gaps header, and
    the MCP search_providers tool returns unlocated: null with unlocated_status: "unknown".
  • MCP search_providers says what its unlocated count means. It now returns
    unlocated_status next to unlocated: counted when unlocated is the exact count, unknown
    when the count didn't finish in time and some candidate addresses may have no location, and
    not_applicable for an NPI lookup. Before, a null count could mean either of the last two.
  • worker migrate and worker migrate --check refuse 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.sh passes 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=off yourself. It now checks the open default, then restarts the API
    with OPENPLANS_PUBLIC_HOUSEHOLD=off and 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 new OPENPLANS_DB_IMAGE setting 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,
    /healthz and /readyz, and has an error table. The configuration guide lists every config
    file key.

Development

  • Code under src/ and plugins/*/src/ no longer uses any. ESLint checks the no-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.sh runs 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_b and provider_search_build. Migrations 1008
    and 1009 each build one index with CREATE 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; or provider_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 PATH with a directory on that disk. It refuses below
    8 GB, and it refuses while worker migrate runs. 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 INSERT has stopped on the database server, and cancel
    it with pg_cancel_backend if 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

Choose a tag to compare

@openhra openhra released this 14 Nov 07:47

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. /status groups 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.json and the
    get_status tool don't change, and their data.states still 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 and sha256
    from /status/operator.json as in the release preflight in docs/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

Choose a tag to compare

@openhra openhra released this 14 Nov 03:39

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 /readyz answers 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 of pending files. A down database gives
    db_down, and a journal that can't be read gives schema_unknown.
  • Pending migrations answer 503, not 500. While a migration is pending, the native and
    compatibility routes answer 503 with the code schema_not_ready and a Retry-After header.
    MCP answers 503 with a JSON-RPC error whose data.reason is schema_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.
  • /healthz is 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
    pending count. A Compose health check on /healthz behaves 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 504 query_timeout, described below.
  • The PGlite server refuses an unmigrated database. npm run api:pglite used 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 500 INTERNAL_ERROR. MCP tools answer the code query_timeout with retryable: 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/ to tests/, next to its only test. The build no
    longer compiles it into dist/, so the image no longer carries it.
  • Ingest code opens downloaded files only through the snapshot store. A test fails when code
    under src/ingest or src/worker builds a raw/ path itself.

Upgrading

  • Pull the new image and run the migrations. Migration 1006 builds one index on address_point
    with CREATE INDEX CONCURRENTLY, so the old version keeps serving while it builds. On a large
    provider load the build can take several minutes, and /readyz answers 503
    schema_not_ready until it finishes. If the build fails, it leaves an invalid index. Drop it
    with DROP 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.1 and
    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 /healthz for
    liveness. A 200 from /healthz no 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

Choose a tag to compare

@openhra openhra released this 13 Nov 17:37

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_network or quote_plans answers unknown, the record's gaps now holds the
    native reason, such as source_set_not_available. Before, only answers from the CMS fallback
    carried it.
  • Empty provider searches say when no registry is loaded. GET /v1/providers answers an empty
    identity search with status: "unknown" and reason: "provider_registry_not_loaded" when no
    NPPES release covers the ZIP's state. The MCP tool search_providers adds the same reason
    (null otherwise), and the compatibility provider search adds it to x-openplans-gaps.
  • Drug search says when terminology is missing. GET /v1/drugs adds terminology_status.
    With no RxNorm release loaded it is unknown, with reason: "rxnorm_terminology_unavailable".
    An empty list with available means 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
    missing MCP-Protocol-Version header, the personalized and estimate access errors,
    AUTH_NOT_CONFIGURED, the concurrency limit and the deadline error. Errors sent before the body
    is parsed keep null: 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.mjs also 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. See scripts/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_providers gains a nullable reason. Clients of GET /v1/drugs see the new
    terminology_status field, and clients of GET /v1/providers may get status: "unknown" with
    provider_registry_not_loaded where 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

Choose a tag to compare

@openhra openhra released this 13 Nov 12:19

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
    gets state_catalog_not_loaded in issues, location_issues and x-openplans-gaps instead of
    an empty list with no reason.
  • Medicare search names its reason. The MCP tool search_medicare_plans adds reason, the
    same code GET /v1/medicare/plans gives, such as catalog_not_loaded when no Medicare catalog
    is loaded. It is null otherwise.
  • Medicare search for an unknown ZIP. GET /v1/medicare/plans and search_medicare_plans
    give reason zip_not_in_loaded_geography for a ZIP outside the loaded geography.

Fixes

  • MCP lookup_geography, search_plans and 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_affordability answered 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_ids now takes plan keys too, and
    identified_at_age and priced_at_age may 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. See docs/configuration.md.

Development

  • scripts/oracle/build-price-check-db.sh builds 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-check builds it and then runs
    the check. See scripts/oracle/README.md.
  • scripts/oracle/surface-sweep.mjs calls 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 when OPENPLANS_SURFACE_SWEEP_DATABASE_URL names 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_plans gains a nullable reason field. In check_ichra_affordability, the
    plan_ids lists under lcsps[] and its by_basis picks accept state plan keys as well as
    HIOS IDs, and identified_at_age and priced_at_age may be null. Clients that parse issues or
    location_issues see state_catalog_not_loaded for 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 and sha256 from /status/operator.json as in the release
    preflight in docs/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.compatKey in the file now guards the compatibility routes,
    and a public.* switch set to false turns that access off. Without a config file nothing
    changes.

OpenPlans v0.4.3

Choose a tag to compare

@openhra openhra released this 13 Nov 08:45

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_PRICES on, 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 a value; otherwise it is bounded. 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
    answers unknown with maximum_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 answers unknown with
    maximum_fair_price_may_apply. The price block gains ingredient, the per-unit price with
    its effective dates, and a maximum_fair_price_total figure, which other drugs report as
    unknown with drug_not_selected. The MCP output schema lists the new fields.
    data/medicare-part-d/drug-lists.json pins the CMS file and holds its prices for 2026 and 2027.
    See docs/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. With price_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-file and reports maximum_fair_price_total.
  • Plan lists say why they may be short. GET /v1/plans and POST /v1/quotes add
    issues, and the MCP tools search_plans and quote_plans add location_issues. Each lists
    reason codes: zip_limited_service_area when 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 as template_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
    reason zip_not_in_loaded_geography instead of unknown. A New York or Vermont county without
    its state catalog has reason state_catalog_not_loaded instead of unsupported_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 to partd_plan_unit_cost,
    partd_pricing_release and partd_dispensing_fee_range move 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. checkCatalogTriggers reports a
    missing or disabled trigger on these tables. See src/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) and cmsFallback.quotes used 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.apiKey and access.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" in docs/configuration.md.
  • Data directory and egress country in the config file. access.dataDir and
    access.egressCountry now 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.dataDir also sets the root of the local blob store unless the file sets
    blobs.root. scripts/smoke.sh and src/ingest/geocode/geocoder.sh still read only
    OPENPLANS_DATA_DIR.
  • Slack plugin 0.2.0 posts rollbacks. The Slack plugin posts release.rolled_back as a
    warning, for example OpenPlans: Release rolled back from 1.4.0 to 1.3.2. It names the two
    versions and never the image ID. Without an events option it posts rollbacks as soon as 0.2.0
    loads. With an events list, add "release.rolled_back" to get them. With minSeverity set
    to error, 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.sh runs one slice of the tests when
    OPENPLANS_CI_SHARD is set. The OpenPlans / macOS check 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_plans answered 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.md now lists the estimate statuses, the maximum fair price reasons and the
    price check as the code has them.
  • docs/ichra.md covers the PY2025 look-back, the reasons a quote asks for a ZIP, and the New
    York rate source override.
  • docs/configuration.md lists every switch with its config key and environment variable.
    .env.example lists the two drug-cost switches.
  • The API README describes the zip_not_in_loaded_geography and state_catalog_not_loaded
    benchmark reasons. docs/migrations.md counts migrations through 1005, and the plugin docs
    describe release.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 --check classes 1005 as risky, because the classifier has no rule that
    clears a dropped trigger. The section on 1005 in docs/migrations.md explains 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.0 and the
    sha256 given in "Upgrade to Slack 0.2.0" in docs/plugins-operations.md. Version 0.1.0 refuses
    "release.rolled_back" in events, so change that list only together with the upgrade.
  • If you parse plan search or quote responses, expect the new issues field on REST and
    location_issues on MCP, and the two new subsidy reason codes. The compatibility search adds
    the codes to x-openplans-gaps.
  • Check your config file before upgrading. If it sets compose.*, geocoder.*, runners.*,
    cmsFallback.apiKey, access.egressFile or access.egressSha256, move the v...
Read more

OpenPlans v0.4.2

Choose a tag to compare

@openhra openhra released this 13 Nov 03:12

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 returns location_requires_zip with reason
    zip_limited_service_area, the same answer as for part-county silver plans, and the credit
    and net premium are null until 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 a value, bounded or unknown. A bounded figure has
    cents: null with minimum_cents and maximum_cents, and the answer never picks one amount
    inside the range. Each priced fill carries a price block that cites its pricing row and fee range. A
    release without pricing rows or fee ranges answers unknown with pricing_not_loaded or
    dispensing_fees_not_loaded. /v1/data-availability says 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 the bounded status. docs/medicare.md explains 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 stay unknown. 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 stay unknown. 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_fee reads 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), and unknown with 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 stay unknown. The new
    OPENPLANS_MEDICARE_DRUG_COST_PRICES setting, described above, turns it on.
  • New event release.rolled_back. The plugin event catalog gains release.rolled_back
    (version, imageId, fromVersion), emitted after a hard-release rollback. The webhook plugin
    posts it when its events list 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.sh now checks 2026
    plan-average prices against its own reading of the cached quarterly archive when
    OPENPLANS_PRICE_CHECK_DATABASE_URL names a database with that release's pricing and
    dispensing-fee tables. Without one, the step prints SKIP. 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 answers unknown with
    zip_not_in_loaded_geography. New York and Vermont rates come from a state catalog. When
    none is loaded for the year, they answer unsupported_rating_method with
    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 pass migrate --check when 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 pricing if you want unit costs
    available to the reader.
  • partd_unit_cost from migration 950 is no longer read or written. A later migration drops it.