Known issues

Defects we have reproduced in the UCP reference stack

Each row is a defect in a published artifact around the specification — an SDK, a sample, the official conformance suite, our own golden server — with a command you can run, what the pinned spec text expects, what the artifact does, and the status on each released cut. Rows are re-verified within thirty days and carry a review date; a finding that was refuted is removed from this file rather than labeled. Source of truth: conformance/ci/known_issues.json in the repository, validated in CI.

10
issues tracked
10
open on a published cut
7
have a fix on some cut
3
no fix anywhere yet

By artifact: golden-0825 1 · js-sdk 2 · official-conformance 1 · python-sdk 1 · samples-node 1 · samples-python 1 · ucp-schema 1 · ucp-spec 2. Spec pin cd78fb38 (2026-08-25). Latest re-verification 2026-10-16. Machine-readable: known-issues.json.

KI-001 python-sdk generated pydantic models (schema constraints)

ucp-sdk 0.5.0 drops four constraint families the pinned 08-25 schemas carry: JWK conditional rules (5), C62 scale, the maxProperties family, discriminator array-retyping. Every published cut predates the fixes.

Reproduce
conformance/.sdk-venvs/ucp-sdk-tag/bin/python conformance/selfcheck/validate_dual_oracle.py --version 2026-08-25 --pydantic
expected each pinned constraint rejects its negative payload
observed the older named probe, conformance/selfcheck/sdk_constraints_probe.py, does NOT run against 0.5.0: it imports ucp_sdk.models.schemas.shopping.types.context, which moved to common.types.context when ucp#741 moved the shared types out of shopping. The gate above is what measures this every run; the 2026-10-09 nightly read pydantic-tag 0.5.0 agree 13, acknowledged drops 7, NEW 0, stale 0, expired 0. All four upstream fixes merged 2026-09-01 and 09-04 but the 0.5.0 tag was cut 2026-08-27, before them, so the tag still drops. See known_sdk_drops.json
Status by cut
  • open PyPI ucp-sdk 0.5.0 (tag v2026-08-25, b6f9b91c)
  • fixed main 836b0228 — python-sdk#89 #91 #93 merged (836b0228); ledger G1
Filed
Provenance
origin theirs · confidence high · re-verified 2026-10-11 · review by 2026-12-08 · ledger row G1

KI-002 js-sdk writeCompatibilityDiscoverySchemas / declarations generator

npm @ucp-js/sdk 0.5.1 ships the extends-stub twin of the merged #55 fix (maxProperties / extends / declarations): generated compatibility discovery schemas are incomplete at the published cut.

Reproduce
npm view @ucp-js/sdk version && grep -n extends node_modules/@ucp-js/sdk/dist/schemas/*.d.ts
expected generated declarations carry the extends/maxProperties members
observed 0.5.1 lacks them; main has them
Status by cut
  • open npm 0.5.1
  • fixed main 99572ca8 — js-sdk#63 merged 2026-09-07 (99572ca8); ledger G3
Filed
Provenance
origin theirs · confidence high · re-verified 2026-10-11 · review by 2026-12-08 · ledger row G3

KI-003 js-sdk UcpDiscoveryProfileSchema

UcpDiscoveryProfileSchema models `capabilities` as an ARRAY; the spec (2026-04-08 and 2026-08-25) defines a record keyed by reverse-domain capability name whose values are arrays.

Reproduce
node -e "const s=require('@ucp-js/sdk');console.log(JSON.stringify(s.UcpDiscoveryProfileSchema.shape.ucp.shape.capabilities._def.typeName))"
expected ZodRecord (object keyed by capability name)
observed ZodArray at 0.5.1 (re-run 2026-10-11 against the published package: capabilities typeName ZodArray; spec_generated.js:1560 reads `capabilities: z.array(CapabilityDiscoverySchema)`)
Status by cut
  • open npm 0.5.1 — The npm dist-tag latest is still 0.5.1, published 2026-09-02, which predates the 2026-09-23 fix, so the published package cannot carry it. Checked against the registry on 2026-10-16: the version list ends 0.5.0, 0.5.1 with no release since. The ZodArray observation in the repro was last executed 2026-10-11 against that same published version.
  • fixed main 6f7a6da7 — js-sdk#73 (ours) merged 2026-09-23T15:09:13Z and closed js-sdk#72 (ours) one second later. Verified at main 6f7a6da7 on 2026-10-16: UcpDiscoveryProfileSchema.ucp is UcpSchema (spec_generated.ts:3606) and UcpSchema.capabilities is z.record(z.string(), z.array(CapabilityResponseSchema)) with a reverse-domain key refinement (:2738), so the exact path the repro walks now resolves to a record rather than an array.
Filed
Provenance
origin theirs · confidence high · re-verified 2026-10-16 · review by 2026-12-08 · ledger row G5

KI-004 ucp-schema definition selection (--def) and --schema-local-base

Crate 1.4.1 and the pinned 9b5c3206 crash (exit 134) on 08-25 def-selection patterns (#45/#46 class); the post-#66 head b52518f5 fixes the crash but regresses --schema-local-base (base segment doubled; A/B proven, old Valid / head rc 2).

Reproduce
echo '{"handler_id":"h","type":"card"}' > inst.json && conformance/.vendor/ucp-schema/target/release/ucp-schema validate inst.json --op create --schema conformance/.vendor/ucp-2026-08-25/source/schemas/common/types/payment_instrument.json --def selected_payment_instrument
expected a validation verdict
observed exit 134 with a stack overflow abort in the main thread, on both the installed 1.4.1 and the vendored pinned build, re-run 2026-10-11 with the recipe recorded in ucp-schema#45. An earlier re-read of this row probed payment_split_payments.json --def dev.ucp.shopping.checkout, which is not the crash pattern and exits 1 with a clean validation error, and wrongly recorded the row as not reproducing
Status by cut
  • open crate 1.4.1
  • open 9b5c3206 (pinned)
  • fixed main b52518f5 — ucp-schema#66 merged (b52518f5) fixes the crash; the --schema-local-base regression there was open at that head (ledger G6). CORRECTED 2026-10-16: this row said '#72 pending', but ucp-schema#72 MERGED 2026-10-07T11:35:32Z, four days before the 2026-10-11 re-verification that did not catch it. Whether that merge clears the --schema-local-base regression at current main is NOT re-verified here; it needs the A/B recipe re-run against a fresh build, and no claim either way is published until it is.
Filed
Provenance
origin theirs · confidence high · re-verified 2026-10-16 · review by 2026-12-08 · ledger row G6

KI-005 samples-python checkout_service / test helpers (bare ShippingDestination)

Fresh-run CI breaks (117/257 at the former pin 00333a80; 2 OrderTest 500s at 01755bcc): a helper builds a bare ShippingDestination and checkout_service.py:532 raises. Fixed upstream by samples#220, merged 2026-10-01 as 667e7212.

Reproduce
cd conformance/.vendor/samples/rest/python/server && uv run pytest -q
expected all tests OK
observed all tests OK at the current pin cdb291c4 (279 passed, 12 subtests, no 500s and no checkout_service reference); the former path rest/python is not a uv project root and never was; only rest/python/server carries a pyproject, at both the old and the new pin
Status by cut
  • open samples 00333a80 (pinned)
  • open samples 01755bcc
  • fixed conformance#96 (helpers) — conformance#96 merged (FanouZeng-TT) for the helper half; samples#220 open for the service half; ledger G10
  • fixed samples cdb291c4 (pinned 2026-10-11) — samples#220 merged 2026-10-01 as 667e7212; at this pin the server suite is 279 passed with no 500s and the official crosscheck reads 77 tests 77 pass 0 fail, up from 75/2
Filed
Provenance
origin shared · confidence high · re-verified 2026-10-11 · review by 2026-12-08 · ledger row G10

KI-006 samples-node production start path (npm start)

`npm start` runs dist/index.js, which tsc never emits (the entry lands at dist/src/index.js); running that directly fails ERR_MODULE_NOT_FOUND on extensionless relative imports, because package.json sets type module while tsconfig sets moduleResolution bundler. samples#58 closed 2026-04 unfixed.

Reproduce
cd conformance/.vendor/samples/rest/nodejs && npm run build && npm start
expected server listens
observed re-run 2026-10-11 at pin cdb291c4: npm run build exits 0 and emits dist/src/index.js but no dist/index.js, so npm start throws; node dist/src/index.js fails ERR_MODULE_NOT_FOUND on dist/src/api/checkout. 39 extensionless relative imports across 13 emitted files (was 37)
Status by cut
  • open samples 01755bcc
  • open samples cdb291c4
Filed
Provenance
origin theirs · confidence high · re-verified 2026-10-11 · review by 2026-12-08 · ledger row R21

KI-007 official-conformance integration_test_utils / DEFAULT_UCP_VERSION

The official conformance suite has zero 2026-08-25 coverage: DEFAULT_UCP_VERSION="2026-04-08" (integration_test_utils.py:59), ucp-sdk==0.4.4 pin, HEAD predates the release.

Reproduce
grep -n DEFAULT_UCP_VERSION conformance/.vendor/conformance/integration_test_utils.py
expected a 2026-08-25 default or matrix
observed "2026-04-08" only
Status by cut
  • open conformance 016ecbc
  • open conformance fdbdafd (pinned)
Filed
Provenance
origin theirs · confidence high · re-verified 2026-10-11 · review by 2026-12-08 · ledger row S4

KI-008 ucp-spec release tag v2026-04-08

The v2026-04-08 tag was re-pointed on 2026-09-09 (tag object ebac9d15 -> a25a4a24, #813 loyalty backport: +19 register MUSTs, +common/loyalty.json). Our lock pinned a2d8bf0b until the D2-15 re-pin of 2026-09-11 (decision 3); a release tag moving after publication is the upstream fact recorded here.

Reproduce
python3 conformance/ci/sources_age.py --check
expected tag v2026-04-08 == the locked commit (a25a4a24 since 2026-09-11)
observed sources-age: OK — all 4 pinned spec tag(s) still carry their locked identity (tag object + dereferenced commit); before the re-pin: TAG MOVED v2026-04-08 -> a25a4a24 (acknowledged)
Status by cut
  • open ucp tag v2026-04-08 @ a25a4a24
  • fixed spck SOURCES.lock 2026-04-08 @ a25a4a24 (re-pinned 2026-09-11) — D2-15 (2026-09-11): SOURCES.lock.json 2026-04-08 commit a2d8bf0b -> a25a4a24, tag_move_observed -> tag_move_resolved; known_tag_moves.json entry retired; sources_age.py --check -> OK, no TAG MOVED; register 1875/1875 verified at the new pin; ledger R20
Filed
Provenance
origin theirs · confidence high · re-verified 2026-10-11 · review by 2026-12-08 · ledger row R20

KI-009 ucp-spec signatures.md REPLAY-002 (payload byte fidelity)

REPLAY-002 requires byte-identical replay detection but the released text leaves canonicalisation vs raw-byte comparison ambiguous; golden-0825 implements the literal reading (seq_invariants I10 enforce; report mode for user-facing runs until F3-f is answered).

Reproduce
python3 conformance/ci/seqfuzz_gate.py
expected one unambiguous comparison rule
observed the former command named a --only flag that golden_check_08_25.py does not define, so it selected nothing and ran the whole module. The real implementation is conformance/ci/seq_invariants.py I10 replay_reserialized, whose mode comes from conformance/ci/replay_mode.json. Latest measurement: 2776 I10 hits over 27818 requests and 4751 sequences, counted as PENDING D3-23 because golden-0825 still hashes the parsed body (checkout_service.py _compute_hash, sort_keys) while the spec matches raw body bytes
Status by cut
  • open ucp cd78fb38 (pinned 2026-08-25)
Filed
Provenance
origin shared · confidence medium · re-verified 2026-10-11 · review by 2026-12-08 · ledger row G13

KI-010 golden-0825 unknown-route error envelope

golden-0825 answers an unknown route with FastAPI's `{"detail":"Not Found"}` 404 instead of the UCP error envelope, and accepts unadvertised versions; fixed by C3 (D3-04) in Wave 0.

Reproduce
PORT=8194 DB_DIR=$(mktemp -d) conformance/testbed/golden-0825/serve_golden_0825.sh && curl -s localhost:8194/nope
expected UCP error envelope 404
observed 404 with the UCP envelope as of 2026-10-11: {"ucp":{"version":"2026-08-25","status":"error"},"messages":[{"type":"error","code":"not_found","content":"Not Found","severity":"unrecoverable"}]}. It answered FastAPI {"detail":"Not Found"} before C3 (D3-04)
Status by cut
  • open golden-0825 @ f9cc470
  • fixed golden-0825 @ faedb2b — re-probed 2026-10-11: GET /nope returns 404 with the UCP envelope {ucp:{version 2026-08-25, status error}, messages:[{type error, code not_found, severity unrecoverable}]}, not FastAPI detail Not Found. Fixed by C3 (D3-04) in Wave 0 as the symptom records
Filed
not yet filed
Provenance
origin ours · confidence high · re-verified 2026-10-11 · review by 2026-12-08 · ledger row R23