npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@claimseed/core

v0.7.0

Published

Render fully synthetic US medical-billing specimen documents (EOB, MSN, bills, notices) from seeded data, and score extractors against their answer keys

Readme

@claimseed/core

@claimseed/core renders fully synthetic US medical-billing specimen documents (Medicare Summary Notices, itemized provider bills, Medicare Advantage explanations of benefits and, over time, other notices) as PDFs with a machine-readable ground truth beside each one. Every value on a page is derived from a seed by a small rules engine (fictional people and facilities, public fee-schedule amounts, Original Medicare Part B adjudication or a fictional Medicare Advantage plan's), and a scenario file decides which error, if any, is deliberately injected and which public rule it breaks. The output exists to test extractors, bill-review tools and training pipelines; nothing in it is, or is derived from, a real document.

CLI

# what can be rendered
node src/cli.js list                 # every type/scenario
node src/cli.js list msn             # one type

# data + ground truth as JSON on stdout, no browser needed
node src/cli.js generate msn baseline-clean --seed demo

# PDF + <name>.ground-truth.json in DIR
node src/cli.js render msn baseline-clean --seed demo --out ./output
node src/cli.js render msn baseline-clean --seed demo --out ./output --degrade scan   # also fax, photo, low-res
node src/cli.js render msn baseline-clean --seed demo --out ./output --also 835       # also the X12 835 of the same claims
node src/cli.js render itemized-bill balance-billing --seed demo --out ./output
node src/cli.js render ppo-eob baseline-clean --seed demo --out ./output   # also hmo-eob
node src/cli.js render ppo-eob baseline-clean --seed demo --out ./output --layout-variant p07   # also seeded, all; not msn
# also a provider's statement for one claim, with a balance due above the EOB's member share (.bill.pdf and its key)
node src/cli.js render ppo-eob baseline-clean --seed demo --out ./output --also bill --bill over-owed

# a set: PDFs, answer keys and manifest.jsonl (SHA-256 of each file, the degradation preset or null, claimseed and Chrome versions) in a new DIR;
# with --also 835 (types msn, ppo-eob and hmo-eob only), each document also gets its .835, listed in the manifest with its SHA-256
node src/cli.js batch --types msn,itemized-bill --seeds 50 --out ./set          # --scenarios all|S1,S2  --seed-prefix P  --degrade PRESET
node src/cli.js batch --types ppo-eob,hmo-eob --seeds 20 --layout-variant seeded --out ./set   # or an id, or all; never with msn
# blind: documents named by an opaque id, never the scenario, errors or seed; answer keys (and a batch's manifest) in a folder apart
node src/cli.js render msn baseline-clean --seed demo --out ./output --blind-keys ./keys   # not ./output or a folder inside it
node src/cli.js batch --types msn,itemized-bill --seeds 50 --out ./set --blind-keys ./keys
node src/cli.js batch --types msn,itemized-bill --seeds 50 --out ./set --blind-keys ./keys --blind-salt SALT   # a key's salt: the same set
# plus a provider's statement per EOB as its own blind document (over-owed where allowed, else clean); see pairs.jsonl
node src/cli.js batch --types ppo-eob,hmo-eob --seeds 20 --out ./set --blind-keys ./keys --also bill --bill over-owed
# the published set "standard": 1,022 blind documents fixed by the set file (no type, scenario, seed, degrade, 835 or layout options)
node src/cli.js batch --set standard --out ./documents --blind-keys ./keys   # --blind-salt SALT (from set.json): the same content again

# score an extractor's report (see "Scoring an extractor" below)
node src/cli.js verify --manifest ./set/manifest.jsonl --outputs ./reports     # one <pdf name>.json per document
node src/cli.js verify --answer-key ./set/X.ground-truth.json --output report.json
node src/cli.js verify msn duplicate-office-visit --seed demo --output report.json   # rebuilds the key from the seed
node src/cli.js verify ppo-eob duplicate-visit --seed demo --layout-variant p07 --output report.json   # a variant's key

Rendering needs a Chrome or Chromium binary. The engine looks at $CLAIMSEED_CHROME, then $PUPPETEER_EXECUTABLE_PATH, then the usual install paths; set CLAIMSEED_NO_SANDBOX=1 only inside a locked-down container. Output files are named <type>_<scenario>_<seed>.pdf and <type>_<scenario>_<seed>.ground-truth.json (schema: schemas/ground-truth.schema.json in the repository — not in the npm package — and validated by the test suite). Same seed, same scenario, same package version → byte-identical data. Every PDF carries Subject: synthetic specimen, not a real document in its metadata, a specimen band at the foot of every page and a diagonal watermark drawn as shapes (so text extraction never sees stray letters); the markers are stamped into the finished PDF inside mergePdfs, which every render function goes through, whether it is reached from the CLI or from the library.

Library

import { generateData, listScenarios, render, RENDERERS, scoreExtraction, verifyFromSeed, renderBatch } from '@claimseed/core';
listScenarios('msn');                                                             // ['baseline-clean', ...]
const { data, groundTruth } = generateData({ type: 'msn', scenario: 'baseline-clean', seed: 'demo' });
const out = await render({ type: 'msn', scenario: 'baseline-clean', seed: 'demo', outDir: './out' });  // { pdf, groundTruth, bytes }
const score = scoreExtraction(groundTruth, { fields: { /* path: value */ }, errors: [ /* { kind, fieldRef } */ ] });
await renderBatch({ types: ['msn'], scenarios: 'all', seeds: 20, outDir: './set' });                 // { count, manifest }
await render({ type: 'ppo-eob', scenario: 'baseline-clean', seed: 'demo', outDir: './out', layoutVariant: 'p07' });  // or 'seeded'

RENDERERS[type](data, stock, workDir, { band, title }) is the lower-level entry the CLI and render() use; it returns the path of a finished, stamped PDF inside workDir.

npm test          # unit tests, including one render-free pass over every scenario with many seeds
npm run check     # repo-wide synthetic-data checks (sources present, no real-format NPIs, phones in the fiction block)

Degraded copies

--degrade scan|fax|photo|low-res (on render and batch) and renderDegraded({ type, scenario, seed, preset, outDir }) make a scanned-looking copy of a document:

| Preset | What it does | | --- | --- | | scan | 200 dpi; off-white paper, a turn under 1 degree and a small shift, softening, grain and dust; JPEG | | fax | 200 dpi black and white after a threshold, standard (half vertical resolution) or fine, a turn, speckle and line streaks, the watermark printed again as a dot pattern; PNG | | photo | 150 dpi; the page on a table, the far edge narrower, a turn of up to 4 degrees, uneven light, blur and grain; JPEG | | low-res | 60 to 90 dpi, heavy JPEG compression |

Any other preset, or an empty value such as --degrade '', is refused with exit code 2 before anything is rendered or written, and the error message does not repeat the value. Every option of the command line refuses an empty value the same way. An unknown option, the --name=value form, an option given twice and an extra argument are refused too.

Each page of the stamped PDF is drawn with PDF.js in an isolated page of the browser (src/pdf-raster.js), degraded there with settings from the seed, and put back together as an image-only PDF. That PDF is then stamped like every other claimseed PDF, so the band, the watermark and the specimen metadata sit on top of the degraded pages. Page images are drawn from the stamped PDF and carry the file markers. render --degrade writes <type>_<scenario>_<seed>_<preset>.pdf, its .ground-truth.json and _p<N>.jpg (.png for a fax); batch --degrade writes the PDF and answer key of each document, without page images. The answer key keeps the document's fields and errors and records degradation and degradationParams (ground truth 1.2 and later). The same seed always gives the same settings; the pictures match within a small pixel tolerance on one Chrome build.

The claims block

Beside documents[0].fields (every printed value), the answer key's claims block is the adjudication the document was assembled from: one entry per claim, and per line the code, units, date, charged, allowed, approved, paid and what the patient may be billed, after any planted errors. From ground truth 1.3 each line also splits the patient's share into toDeductible, coinsurance, copay and nonCovered (a denied service the patient agreed to pay for), which add up to patientMayBeBilled to the cent; Part B lines have no copay. deductibleMetBefore is the deductible already met before the document's claims. On the Medicare Summary Notice the printed deductible met is deductibleMetBefore plus the lines' deductible, capped at the annual deductible (a scenario that applies the deductible again after it was met shows the extra on the lines, above the cap); on the PPO EOB it is deductibleMetBefore plus the lines' deductible; the itemized bill prints the lines' deductible as deductible applied; the HMO plan has no deductible. The split is derived from the adjudication: it changes no printed value and no field.

Layout variants

--layout-variant <id> (on generate, render, batch and the seed form of verify, and with --degrade) and layoutVariant (on generateData, render, renderDegraded, verifyFromSeed and renderBatch) print the same document in another layout. The itemized bill, the PPO EOB and the HMO EOB each publish a closed list of 12 ids (b01-b12, p01-p12, h01-h12) in data/<type>/variants.json. An id fixes four things: the column order; a set of header and title wording from data/<type>/labels.json (base is the standard wording, alt-a and alt-b the others); a style (font, density and palette); and how a table continued on the next page is marked (repeat prints the claim or department-group header again with a "continued" mark, marker prints only a "continued" line). seeded picks an id from the seed alone, not from the type or scenario, so one seed takes the same position in every type's list (p04, h04 and b04 together) and a batch over several types is correlated; pass explicit ids to spread layouts across types. all (render and batch only) writes one document per id. The Medicare Summary Notice has one national format and takes no variant.

A variant never changes the data, any amount, any required item, the order of the EOBs' money columns (amount billed, approved, plan's share, your share), the bill's charge column (always last), the date and money formats or the specimen markers. A varied bill prints each line's department code in its department column, where the standard bill leaves that cell blank under the group header, and its "SPECIMEN" badge gets a light background so it stays legible on every header color. Files are named <type>_<scenario>_<seed>.<id>.pdf (a degraded copy <type>_<scenario>_<seed>.<id>_<preset>.pdf), and a batch manifest line carries layoutVariant.

The answer key of a varied document is ground truth 1.4: documents[0].layout is <type>.<id> (for example ppo-eob.p07) and documents[0].layoutVariant records { id, columns, labels, style, breaks }. Nothing else differs from the key of the standard document with the same seed except the page count and the PDF's hash, and the 835 is identical. With no variant the output is byte for byte what 0.4.0 printed and the key stays at 1.3. An unknown id, an id of another type, an empty or over-long value, seeded or all on the MSN, all outside render and batch, a batch that mixes the MSN with seeded or all, and the option given twice are refused (exit code 2 on the command line, an error from the library) with a message that does not repeat the value.

X12 835 remittances

--also 835 (on render and batch) and render({ ..., also: '835' }) write the X12 005010X221A1 835 of a Medicare Summary Notice or a Medicare Advantage EOB from the same claims (src/x12/remittance.js); remittanceFor({ type, scenario, seed }) returns it as { text, groundTruth } without writing anything. The itemized bill has none: it prints no per-line payer amounts, and an institutional remittance needs data it does not carry.

  • What the file holds. One interchange and one functional group; one transaction per payee (grouped by NPI). The payment record is remittance information only (BPR01 I) for a fictional check (BPR04 CHK), or H/NON/$0 for a transaction whose claims pay nothing, with no routing or account numbers (BPR05 to BPR15 empty). Per claim a CLP (status 1, or 4 when every line is denied; claim filing indicator MB for the MSN, 16 for the Medicare Advantage EOBs), the patient (NM1*QC), and per line an SVC, its date, its adjustments and the approved amount (AMT*B6).
  • Adjustments. Code values only, never their descriptions: CO-45 for the charge above the approved amount; PR-1, PR-2 and PR-3 for the deductible, coinsurance and copay from the claims block; a line denied as not medically necessary is adjusted in full under CARC 50 with group PR when the notice says the patient may be billed, CO when it says the patient owes nothing. The duplicate scenarios bill a service twice; a payer handling them correctly would deny the repeat as OA-18 (this is the expected handling the errors describe, not something the file shows). Code values are X12's (x12.org/codes); claimseed uses the values only.
  • Values. The document's own: charged, approved, paid and the patient's share as the PDF prints them, so a planted error stays where the PDF has it. In the answer key, documents[1] is the 835 (type x12-835, its SHA-256, its transactions and the payer), and each error the file carries has x12Ref: <ST02>:CLP<n>:CLP03 (a wrong charged total, which fails the claim balance), CLP04 (paid; claim balance), CLP05 (the patient total; it then differs from the claim's PR adjustments), or <ST02>:CLP<n>:SVC<n> for a line (a duplicate is a repeated service line).
  • Markers. ISA15 is T; the sender and receiver IDs, the payer's name and address and the technical contact (name and a 555-01xx phone) come from data/x12/specimen-strings.json, written without access to any real document, and all say specimen or test. The 835's payer is this specimen payer, not the issuer the PDF prints.
  • Identifiers. Guaranteed never to be real: NPIs start with 9 (NPIs are issued with a first digit of 1 or 2), tax IDs start with 00 (not on the IRS list of prefixes), Medicare numbers carry a letter Medicare never uses. Recognisable sentinels only: the claim numbers the PDF prints (13 digits starting with 99 on the MSN, CS and 10 digits on the Medicare Advantage EOBs), member IDs (SPEC and 8 digits), and the patient control numbers, check numbers and payer ID (N1*PR with the plan ID qualifier XV), which start with CS. Systems that validate real identifiers may reject them.
  • What real Medicare remittances carry and these do not: the 2% sequestration adjustment (CO-253), remark codes and the MIA, MOA and LQ segments, provider-level adjustments (PLB), and bank data. A file with a planted error is deliberately non-conformant where the error is.
  • Format. Delimiters * ^ > ~; each segment ends with ~ and a line feed, for reading (translators accept it; strip the line feeds for a strict reader). Save the text byte for byte: the answer key holds its SHA-256. The checker in src/x12/check835.js (check835, checkSpecimen835) reads these files; it expects a procedure code of five characters after HC, as every code in reference-data/service-catalog.json is.

Provider statements (Medicare Advantage pairs)

Beside a Medicare Advantage EOB (ppo-eob or hmo-eob, claimseed's fictional PPO and HMO), claimseed can render the provider's statement for one claim of that EOB: a one-page patient statement from the provider, of document type provider-statement. Which claim it bills is drawn from the seed. The EOB is exactly the same with or without its statement.

The statement lists the claim's lines (date, code, description, units, charge) and an account summary: Total Charges, Contractual Adjustment, Denied by Your Plan (only when a line was denied), Paid by Your Plan, Payments Received and Balance Due. On a correct statement the balance due is the member share the EOB shows for that claim.

Variants

The variant is the value of bill. It gives the statement its own error or decoy, or none:

  • clean (the default): no error of its own.
  • over-owed: the contractual adjustment is too small, so the balance due is more than the EOB's member share. Error kind bill-vs-eob-mismatch, at the balance due.
  • denied-line-billed: a line the plan denied is billed to the patient, so the balance due is more than the EOB's member share by that line's charge. Error kind bill-vs-eob-mismatch.
  • payment-misposted: Paid by Your Plan differs from what the EOB says the plan paid, and the adjustment moves the other way, so the balance due is still right. Error kind bill-payment-mismatch, severity low.
  • paid-at-visit: a decoy. Payments Received shows the copay paid at the visit, so the balance due is less than the EOB's member share, and that is correct.
  • over-owed-with-payment: the paid-at-visit decoy and the over-owed error on one statement.

A variant applies only where the billed claim allows it; for example, denied-line-billed needs a denied line on that claim. A single render refuses a variant that does not apply. A batch renders that statement clean instead, and its answer key says which variant it got (pair.variant). When the EOB claim a statement bills has a planted math error in its printed total (the total does not add up from its lines), the statement follows the EOB's lines, which are right, not the misprinted total. The statement's own error variants do not apply to that claim, so only a clean statement is made for it.

Some statements also carry, keyed on their own lines, errors and decoys that the EOB has on that claim and that the provider made: a line billed twice, a wrong date of service, a service repeated on another date, a charge far above the approved amount.

Options

On the command line, render takes --also bill (or --also 835,bill for the 835 too) and --bill <variant>. In the library, render() takes also: 'bill' or also: ['835', 'bill'], bill (the variant) and billParams, the variant's amounts in dollars, given to the cent (for example by: 9.84 is $9.84): by for an error, amount for the decoy. An amount not given is drawn from the seed.

Files and keys

The statement is written as <name>.bill.pdf, with its key in <name>.bill.ground-truth.json, beside the EOB's <name>.pdf and key. Both keys are answer-key version 1.6 and carry pair: role (eob or bill), with (the other document's file name without .pdf, or its blind id), claim, variant and params.

Blind documents

In blind mode the statement has its own opaque id, drawn from the salt, the EOB's id, the statement variant and its amounts, so two statements of one EOB with different variants or amounts have different ids. It is written as <id>.pdf, and its key goes to the keys folder.

Batch

batch takes --also bill and --bill <variant> too. Each statement is written as a document of its own, at its own place in the order (shuffled by the salt when blind). Each statement has its own manifest line, with type provider-statement, the EOB's scenario and seed, and pairOf, the EOB's file name without .pdf or its id. pairs.jsonl in the documents folder publishes the pairing: it lists each pair as { "eob": ..., "bill": ... }, with names or ids only.

Scoring

A report on a statement is scored like any document's, against its own key: with verify --answer-key or a manifest. verifyFromSeed takes document: 'bill' and bill (the variant) to rebuild the statement's key, instead of the EOB's, from the type, scenario and seed.

Not supported yet

A statement has no layout variants of its own, and nothing can ask for one. The EOB's layout variant applies to the EOB. Degraded copies of a statement and statements in a published set are not supported yet. Each is refused with a message.

Scenario files

A scenario is one JSON file at scenarios/<type>/<slug>.json. It describes a situation, not a document: the engine draws the people, providers, codes and amounts from the seed, and the scenario says how many claims, over which period, and which mutations to apply.

{
  "type": "msn",                        // document type; must have an assembler and a renderer (see below)
  "slug": "lab-coinsurance-charged",    // == the file name
  "status": "published",                // "published" or "engine-test" (engine-test files block a release)
  "description": "One or two sentences a tester reads to know what the specimen exercises.",
  "period": { "start": "2026-03-01", "end": "2026-03-31" },   // claims-processed window; year sets the CMS parameters
  "claimCount": 3,                      // claims on the notice; each claim has 1–5 lines
  "claimShapes": ["LAB"],               // optional: force the specialty/shape of claim i so a mutation lands on the
                                        // right kind of line for ANY seed. Shapes: IM, LAB, CARD, OPH, PT, RAD, DERM, FP
  "referenceSurname": true,             // optional: patient surname "Specimen"
  "deductibleMetBefore": 0,             // optional: Part B deductible already met before the period, in dollars
  "mutations": [                        // applied in order; each produces one ground-truth error
    { "op": "apply-cost-share-to-exempt-line", "args": { "claim": 0, "line": 0, "rate": 0.2 },
      "kind": null, "severity": null, "rule": null, "note": null }   // optional overrides of what the op reports
  ],
  "decoys": [                           // optional, every type: correct lines that look wrong,
    { "op": "repeat-service-other-date", "args": { "claim": 1, "line": 0, "days": 7 },   // applied after the mutations
      "rule": "the public rule that makes the line correct (required)", "note": "optional" }
  ],
  "sources": [                          // REQUIRED, 2–4 entries: where the structure, codes and rule came from.
    { "what": "No deductible or coinsurance on lab fee schedule tests", "source": "SSA §1833(a)(1)(D), https://www.ssa.gov/OP_Home/ssact/title18/1833.htm" }
  ]
}

Mutation ops (src/generate/mutations.js) and the error kind each reports:

| op | args | kind | | --- | --- | --- | | duplicate-line | claim, line | duplicate-charge | | break-claim-total | claim, field (maxYouMayBeBilled, amountProviderCharged, medicareApprovedAmount, amountMedicarePaid), by | math-error (override kind to subtotals-mismatch on a bill) | | apply-cost-share-to-exempt-line | claim, line, rate | cost-sharing-error on a lab line, preventive-cost-sharing on a preventive line | | reapply-deductible | claim, line | deductible-misapplied | | deny-line | claim, line, note { text, rule } | coverage-denial | | shift-date | claim, line, days | service-date-anomaly | | overprice-line | claim, line, factor | fee-schedule-overcharge | | bill-above-approved | claim, line, mode (unpaid-balance or extra), by | assignment-violation (provider-side documents only) |

Indices are zero-based; claim must be below claimCount. Line 0 always exists; use claimShapes when a mutation needs a particular kind of line or a line beyond index 0 (for example DERM always has two lines).

Decoy ops (same file) plant a line that looks like an error but follows the rules. Each is listed in the ground truth's decoys[] with its kind, place and the rule the scenario cites, never in errors[]; an op refuses a line that carries an error or another decoy.

| op | args | kind | what it does | | --- | --- | --- | --- | | repeat-service-other-date | claim, line, days | repeat-service-different-date | adds the same service days later (or earlier, to stay in the period), adjudicated as its own service; refuses preventive services, new-patient visits and HbA1c | | charge-far-above-approved | claim, line, factor (default 4) | charge-above-approved | raises only the provider's charge; the approved amount, payment and patient share stay put |

The Medicare Advantage EOBs take operations of their own, named with an ma- prefix (src/generate/ma-mutations.js): the errors ma-duplicate-line, ma-shift-date, ma-deny-line, ma-break-claim-total, ma-cost-share-on-exempt-line, ma-reapply-deductible and ma-share-after-oop-max, and the decoys ma-repeat-service-other-date, ma-approved-below-copay, ma-charge-far-above-approved, ma-oop-cap-partial-share and ma-partial-deductible. Such a scenario may set maPriorOop, what the member had paid out of pocket before the period, and, on the PPO, maDeductibleMetBefore, the part of it that went to the deductible. docs/error-taxonomy.md gives the kind each op reports and its rule; the MCP resource catalog://mutations lists the ops the published scenarios use, with the kinds they produce and the scenarios that use them.

Blind documents and published sets

For tools that must not see answers, --blind-keys KEYDIR (on render and batch) and blind: true with keysDir (on render and renderBatch) name each document by an opaque id (doc- and 16 hexadecimal digits). Its specimen band, PDF title, file names, page-image markers and 835 carry that id, never the scenario, planted errors or seed. The specimen markers stay; only the scenario words are gone. Answer keys and a batch's manifest go to KEYDIR, never the documents' folder or one inside it. A degraded copy is blind too, with its own id.

Content comes from a seed derived from a salt, 128 random bits drawn per set, recorded in every key, so nobody can rebuild a document from a guessed scenario and seed and match a printed claim number. --blind-salt SALT or blind: { salt } (32 lowercase hexadecimal digits from an earlier set's key) makes the same set again; documents are written in an order drawn from the salt. Keys (ground truth 1.5 for a blind document alone, 1.6 for either document of a pair) hold a blind object: id, salt, seed and layoutVariant as asked, copyOf on a degraded copy, set and canary in a published set (every manifest line carries the canary too). verify --manifest scores a blind set exactly as an open set.

--set standard (set: 'standard') makes the published set "standard" of 1,022 blind documents (see the repository README). A set is always blind and its file fixes every document, so --set takes no --types, --scenarios, --seeds, --seed-prefix, --degrade, --also or --layout-variant. Its salt, from set.json or any key, makes the same content again; PDF bytes can differ by machine and Chrome install, so the manifest's SHA-256s name the published files.

await renderBatch({ set: 'standard', outDir: './documents', blind: true, keysDir: './keys' });  // or blind: { salt }

Scoring an extractor

verify compares an extractor's or bill auditor's report with the answer key. The report is JSON in the shape of schemas/extractor-output.schema.json: fields maps answer-key field paths (the keys of documents[0].fields) to the values read, and errors lists { kind, fieldRef | lineRef } for each problem flagged. Either part may be left out.

  • Fields: money is compared to the cent and may be printed text ("$1,234.50"); dates may be ISO, M/D/YYYY or "April 11, 2026"; text ignores case and repeated spaces. The result counts correct, wrong and missing fields and lists their paths.
  • Errors: a flag finds an error when its kind matches and its place names the same line or total (a field inside the line counts; for a duplicate charge, either line of the pair). A second flag on a found error is a repeat, not a false alarm. A flag on a decoy, or on the line a decoy repeats (relatedLineRef), is a false alarm and is listed under decoysFlagged.
  • The report is size-capped (5,000 fields, 1,000 errors, 200-character paths, 1,000-character values) and refused if it has any other shape; the result holds counts, rates and answer-key paths only, never the report's own text.
  • verify --manifest scores a whole set against the answer keys saved with it, after checking each key's SHA-256 against the manifest, so a set is always graded against the keys it was rendered with. It reads only regular files with the names the manifest gives, in the set and report folders: a symbolic link there is not followed, and a folder, FIFO or device is listed as an invalid report (or, in place of an answer key, refused). Only a report that is not there counts as missing; one that holds JSON null, a list or malformed JSON is listed as invalid.
  • Headline figures (fields, errors) count every document of the set: a missing or invalid report scores as an empty one, and so does a part (fields or errors) a report leaves out once any report gives it. Skipping a document never raises field accuracy or recall; precision counts only what was flagged, so read it beside recall. scoredOnly holds the old figures, over scored reports. New breakdowns: byType, byDegradation (clean or the preset) and byKind (expected, found, recall per kind). documents, scored, missingOutputs, invalidOutputs and documentsScored are unchanged.
  • An answer key is checked before scoring: field values must be strings, numbers, booleans or null, error kinds and decoy ids lower-case letters, digits and hyphens, and references strings; any other key is refused.
  • Dates match in any of the supported forms on either side: a key that prints "March 5, 2026" accepts 2026-03-05, and the reverse.

Adding a scenario

  1. Pick the document type and the error kind from docs/error-taxonomy.md. If the kind is new, add a row there with the public rule it violates.
  2. Write scenarios/<type>/<slug>.json as above. Set claimShapes so the mutation lands on the intended kind of line for every seed, and describe the specimen as a tester would want to read it.
  3. Cite 2–4 public sources (CMS manuals and fact sheets, medicare.gov, eCFR, ssa.gov, MLN booklets, NCCI pages) and open every URL before you cite it. Do not cite, consult or describe any real statement.
  4. Run npm test (the catalog test generates every scenario with many seeds) and render it once: node src/cli.js render <type> <slug> --seed test --out /tmp/out, then read the PDF text.

Adding a document type

  1. Templates: templates/<type>/*.html (Nunjucks, extending base-portrait.html) and stock text, labels and colors in data/<type>/stock-content.json. Every sentence of stock content is either verbatim from a public federal model document (the CMS sample MSN, 45 CFR 92 Appendices A/B, HHS and CMS pages) or claimseed's own wording; data/SOURCES.md records which, and scripts/verify-stock-sources.js checks it against the snapshots in data/public-sources/. No real organization's name, logo, colors or boilerplate.
  2. Renderer: a render<Type>(data, stock, outDir) function in src/render.js that paginates and returns the PDF path; register it in RENDERERS in src/layouts.js.
  3. Assembler: src/generate/<type>.js exporting assemble<Type>({ rng, beneficiary, adjudicated, period, dateOfNotice, year, groundTruthErrors }), which turns the shared beneficiary and adjudicated claims into the exact object the templates read. Keys starting with _ are neither rendered nor flattened into ground truth; _groundTruth may override the entities block (providers, identifiers, payer). Register it in ASSEMBLERS in src/generate/index.js. src/generate/itemized-bill.js is the smallest worked example.
  4. Scenarios: at least a clean control and one error scenario in scenarios/<type>/, plus a test in test/generate.test.js that checks the assembled numbers reconcile.

Synthetic-data rules

Everything the engine prints comes from src/generate/lexicon.js (fictional names, fictional streets, real cities so addresses format correctly), from format-valid identifiers that cannot be real (NPIs start with 9 and are Luhn-valid over the 80840 prefix; Medicare numbers carry S in position 2, a letter CMS never uses; phones are a geographic area code plus 555-01xx; facility tax IDs use the unissued 00- prefix; web addresses end in the reserved .example domain), and from amounts the rules engine computes from the service catalog and the CMS annual parameters. Service descriptions are claimseed's plain language, never AMA CPT descriptors; HCPCS Level II codes are preferred; a service added without a verified public price carries "verified": false, a round illustrative allowed, and a sources entry saying where a maintainer should look it up. Contributors never attach, link, paste, or describe from memory any real statement, bill, notice or lab report, never fit anything to one, and never add a real insurer's, pharmacy's or laboratory's name or branding. See docs/synthetic-data-policy.md; npm run check enforces what it can.