Black-box API archaeology
Make yesterday’s client understand tomorrow’s API.
ProtocolSmith designs controlled experiments, discovers undocumented behavioral changes, compiles a constrained compatibility bridge, and verifies whether the unchanged legacy contract is restored.
From evidence to proof.
Muse handles hypothesis formation and experiment design. A deterministic runtime constrains, executes, and verifies every resulting transformation.
Probe both APIs
Capture status codes, response shapes, values, errors, and pagination behavior.
Muse forms hypotheses
Infer field mappings, transformations, and semantic changes using structured outputs.
Compile safe rules
Convert hypotheses into an allowlisted declarative adapter—never arbitrary generated code.
Verify this contract
Replay legacy contracts and produce a machine-readable verification receipt.
Muse tests a causal compatibility hypothesis.
Muse proposed a bounded hypothesis. ProtocolSmith executed baselines, correct-parameter requests, and swapped-name negative controls. The mapping is accepted only when all six deterministic outcomes agree.
Does
page_size
map to
limit?
Candidate hypothesis: legacy query param page_size maps to modern query param limit as limit = page_size, so page_size=1 on GET /v1/customers/{id}/orders should correspond to limit=1 on GET /v2/customers/{id}/orders, pending confirmation from controls where baseline and swapped names both return 2 items while correct name truncates to 1 item
Causally confirmed · 6/6 controls passedVersion-specific parameter mapping confirmed
The candidate mapping was tested with positive and negative controls. Each API returned two items at baseline, ignored the other version’s parameter name, and returned one item only when given its proposed version-specific parameter.
| API | Test | Parameter | Observed | Expected | Result |
|---|---|---|---|---|---|
| Legacy v1 | Baseline | none | 2 | 2 | pass |
| Legacy v1 | Wrong name |
limit=1
|
2 | 2 | pass |
| Legacy v1 | Correct name |
page_size=1
|
1 | 1 | pass |
| Modern v2 | Baseline | none | 2 | 2 | pass |
| Modern v2 | Wrong name |
page_size=1
|
2 | 2 | pass |
| Modern v2 | Correct name |
limit=1
|
1 | 1 | pass |
Discovered compatibility map.
Every rule links legacy and modern behavior to the evidence that supports it.
| # | Category | Legacy | Modern | Confidence | Transformation |
|---|---|---|---|---|---|
| 1 | request parameter rename | $.params.page_size |
$.params.limit |
100% |
View ruleRename query param page_size to limit; integer value passes through unchanged: limit = page_size |
| 2 | response nesting change | $.customer_id |
$.customer.id |
95% |
View ruleMove string value into nested object: modern.customer = {id: legacy.customer_id} |
| 3 | response field rename | $.orders |
$.data |
95% |
View ruleRename top-level array $.orders to $.data; element order preserved, 1:1 element mapping |
| 4 | response field rename | $.orders[].id |
$.data[].order_id |
100% |
View ruleRename field id to order_id; string value identical: order_id = id |
| 5 | response field rename | $.orders[].status |
$.data[].state |
95% |
View ruleRename field status to state; observed values 'paid','shipped' pass through unchanged: state = status |
| 6 | value transformation | $.orders[].total_cents |
$.data[].amount.value |
95% |
View ruleConvert integer cents to decimal string dollars nested under amount: amount.value = format(total_cents/100, '.2f') as string; amount.currency observed as 'USD' with no legacy equivalent; reverse: total_cents = int(round(float(amount.value)*100)) |
| 7 | value transformation | $.orders[].created_at |
$.data[].created |
90% |
View ruleTruncate ISO8601 datetime to date: created = created_at[0:10] (YYYY-MM-DD); time component dropped, reverse requires midnight UTC reconstruction only if needed |
| 8 | pagination change | $.next_page |
$.pagination.next_cursor |
85% |
View ruleMove pagination token into nested object: pagination.next_cursor replaces next_page; both null when no further pages in observations; request pagination controlled by limit |
| 9 | error semantics change | $.status_code |
$.status_code |
95% |
View ruleMissing customer changes from HTTP 404 to HTTP 200 with empty data; adapter must map modern 200 with $.error.type=='unknown_customer' to legacy 404 |
| 10 | error semantics change | $.detail |
$.error |
90% |
View ruleMap modern error {type:'unknown_customer',customer:<id>} to legacy detail {code:'CUSTOMER_NOT_FOUND',message:'Customer does not exist'}; modern error response has $.data=[] and omits $.customer and $.pagination; modern success has no $.error |
The recorded verification replay.
In this benchmark, the unchanged legacy contract succeeds against API v1, fails as expected when sent directly to API v2, and succeeds again through the generated bridge. This button replays the committed, machine-readable receipt generated at 2026-10-31T02:40:39.171881+00:00. It makes no network request and is not a substitute for running the local proof.
Legacy API v1
waitingExpected result: the unchanged client works against its original contract.
No replay yet.
Modern API v2 direct
waitingExpected result: the unchanged legacy client cannot interpret the v2 response without ProtocolSmith.
No replay yet.
ProtocolSmith bridge
waitingExpected result: the generated specification restores the legacy contract.
No replay yet.
Verification receipt.
15 of 15 recorded contract checks passed.
Honest about information loss.
Information loss is disclosed and scoped. Behavior unsupported by evidence fails closed.