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.

Experiments
3
Paired black-box probes
Changes found
10
Evidence-backed differences
Verification
15/15
Deterministic contract checks
Mean confidence
94%
Across inferred changes

From evidence to proof.

Muse handles hypothesis formation and experiment design. A deterministic runtime constrains, executes, and verifies every resulting transformation.

01 / OBSERVE

Probe both APIs

Capture status codes, response shapes, values, errors, and pagination behavior.

02 / REASON

Muse forms hypotheses

Infer field mappings, transformations, and semantic changes using structured outputs.

03 / EXECUTE

Compile safe rules

Convert hypotheses into an allowlisted declarative adapter—never arbitrary generated code.

04 / VERIFY

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.

Model-designed proposal

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 passed
Controlled finding

Version-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.

Six-case causal-control experiment results
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.

Evidence-backed compatibility mappings
# Category Legacy Modern Confidence Transformation
1 request parameter rename $.params.page_size $.params.limit 100%
View rule

Rename query param page_size to limit; integer value passes through unchanged: limit = page_size

2 response nesting change $.customer_id $.customer.id 95%
View rule

Move string value into nested object: modern.customer = {id: legacy.customer_id}

3 response field rename $.orders $.data 95%
View rule

Rename top-level array $.orders to $.data; element order preserved, 1:1 element mapping

4 response field rename $.orders[].id $.data[].order_id 100%
View rule

Rename field id to order_id; string value identical: order_id = id

5 response field rename $.orders[].status $.data[].state 95%
View rule

Rename field status to state; observed values 'paid','shipped' pass through unchanged: state = status

6 value transformation $.orders[].total_cents $.data[].amount.value 95%
View rule

Convert 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 rule

Truncate 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 rule

Move 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 rule

Missing 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 rule

Map 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.

Recorded evidence
Ready to replay the committed receipt

Legacy API v1

waiting

Expected result: the unchanged client works against its original contract.

No replay yet.

Modern API v2 direct

waiting

Expected result: the unchanged legacy client cannot interpret the v2 response without ProtocolSmith.

No replay yet.

ProtocolSmith bridge

waiting

Expected result: the generated specification restores the legacy contract.

No replay yet.

Verification receipt.

15 of 15 recorded contract checks passed.

✓ legacy API succeeds
✓ modern API is directly incompatible
✓ bridge returns legacy success status
✓ generated adapter identity disclosed
✓ root customer identifier preserved
✓ one-order collection size preserved
✓ order field preserved: id
✓ order field preserved: total_cents
✓ order field preserved: status
✓ created_at calendar date preserved
✓ page-size translation preserves two results
✓ pagination value preserved
✓ missing-customer status restored
✓ missing-customer error body restored
✓ lossy date conversion disclosed

Honest about information loss.

Information loss is disclosed and scoped. Behavior unsupported by evidence fails closed.

created_at — The modern API retains only the calendar date. ProtocolSmith reconstructs midnight UTC and exposes an explicit response warning.