rating-api-walkthroughs reproduction

Public source retained with the related article. Generated results, dependency directories, runtime storage, secrets, and oversized binary artifacts are intentionally excluded.

README

# Rating-engine API walkthroughs

These are complete synthetic input documents and observed HTTP exchanges for
twelve walkthroughs of a private logistics rating engine. The examples were
executed against its Go HTTP application, a newly migrated PostgreSQL database
and a task-owned Redis instance. There is no replacement rating calculator.
No production data, customer prices or credentials are included.

The engine itself is private. This pack does not include its executable,
database migrations or a hosted demo. You can inspect every request and
response without access; execution requires an authorized disposable
installation and its normal runtime dependencies. Don't send this authoring
sequence to production. It creates divisions, publishes configuration, issues
runtime credentials and persists rating decisions.

## Run one journey

Download `run.mjs` and a complete numbered directory, preserving its relative
filenames. Use Node.js 22 or later. Supply installation credentials through
environment variables or your existing secret manager:

```sh
export BASE_URL='http://127.0.0.1:8080'
export VERSION_HEADER='<installation API-version header name>'
# Set AUTHOR_TOKEN and READ_TOKEN without recording secrets in shell history.
node run.mjs 01-first-quote
```

The installation-specific header name is anonymized; its wire value is
`2026-03-22`. The separate rating `contract_version` is defined by each model.
AUTHOR_TOKEN must be able to create divisions, author/publish their definition
and issue access tokens. READ_TOKEN must be able to export configuration. The
runner obtains division-bound runtime tokens through the API and holds them
only in memory. Disposable examples use broad `*` abilities; use narrower
production credentials and the installation's normal governance controls.

Each numbered directory has `scenario.json`, complete `definition-N.json`
documents and named evaluation bodies. A step's `file` loads the shared body;
its inline `request` fields overlay that file, so validate, plan and apply
use separate operation metadata. `{{namespace}}` and extracted division IDs
are resolved at runtime. They aren't literal values to send manually.

The runner checks expected HTTP status, business-success flags, option counts,
EUR totals, component currencies, selected row identities and component
groups/scopes/bases. Any mismatch stops the sequence. It doesn't log
authorization headers. Captures redact token/secret fields and known author,
read and issued runtime credential values, including echoes in error text,
paths or object keys. Set CAPTURE_FILE to a new file path to save a redacted exchange
log; existing files are never overwritten. Keep fresh captures outside this
downloaded source tree. Stop the disposable installation and remove its
database and issued credentials when finished; this pack does not delete
application data or revoke tokens on your behalf.

## What each directory tests

| Directory | Reader job |
| --- | --- |
| 01-first-quote | Publish, quote, replay, conflict and denied unbound token |
| 02-chargeable-goods | Four combinations of volumetric weight and battery goods |
| 03-percentage-bases | Independent 10% and 5% bases with component rounding |
| 04-pass-through | Include a fixed fee in the total but exclude it from markup |
| 05-postcode-boundaries | Geographic endpoints and an unmatched control |
| 06-charge-scope | One shipment fee and repeated package fees |
| 07-item-allocation | Move a battery allocation and require the fee reference to follow |
| 08-offer-selection | Resolve an offer before selecting a tariff row |
| 09-load-transition | Classify a load before charging for its treatment |
| 10-multileg-eligibility | Filter a priced service by route eligibility |
| 11-required-capability | Remove declarations at shipment and item scope; expect no option |
| 12-candidate-preview | Compare identical shipments across isolated baseline/candidate models |

`observed.json` contains the actual rating exchanges from the verification
run, with synthetic generated identities and credentials removed where present. It is an observation,
not a fixture the runner feeds back as an answer. Full setup responses are not
duplicated there: the authoring inputs and executable sequence are included,
and CAPTURE_FILE can retain a new full run on an authorized installation.

The rewritten articles also show complete cURL publication/evaluation sequences
and additional model comparisons on the page. Their `observed-variants.json`
files preserve fresh rating requests/responses from those exact shell blocks;
the allocation chapter uses `observed-boundaries.json` for its extra input
cases. These observations are not answers fed into the runner. The shared
Node runner still executes the original cases declared in `scenario.json`;
use the article's shown commands for the additional comparisons. Model changes
are published into new divisions rather than silently replacing a baseline.

These are bounded functional examples, not a benchmark, full migration-parity
certification, arbitrary cross-product coverage or dangerous-goods compliance
advice. The definition API and public example file format are different
contracts. See API_REFERENCE.md for the wire layout and lifecycle.

Retained files