feat(architecture): define language adapter mappings by yshyn-iohk · Pull Request #509 · hyperledger-identus/sdk-rust

yshyn-iohk · 2026-09-30T08:08:42Z

Pull request

Outcome

Defines a canonical, versioned Rust-to-language compatibility contract for the first SDK-TS DID adoption slice. The registry records four DID/DID URL value and error mappings while keeping identus-did values and stable error codes authoritative.

Issue and decision record

Issue: architecture(bindings): specify canonical language adapter and error mappings #505
Parent: milestone(A1): establish the shared compatibility foundation #504
Architecture decisions: ADR 0169, ADR 0170, and ADR 0173
Downstream consumer: canary(bindings): prove an opt-in SDK-TS DID value path through identus-wasm-did #492, after factory: validate capability/change ledgers and generate migration-release evidence #422 and conformance: require risk-routed property fuzz benchmark and differential evidence #501

Factory contract

OpenSpec archive: 2026-09-30-establish-language-adapter-mappings
Planning receipt: issue architecture(bindings): specify canonical language adapter and error mappings #505, contract head 826d6e17a36a224f7156c015ce7c9d46bad20079
Factory readiness and archive guards: passed
Target branch: develop
Required hosted lane: fast; slow remains production-promotion evidence

Scope

closed, versioned language-adapter mapping schema;
four SDK-TS 8.1.4 DID/DID URL seed mappings;
explicit field direction, fidelity, unsupported cases, stable errors, bounds, redaction, lifecycle, rollback, and removal gates;
deterministic Markdown rendering and strict offline validator;
mutation tests isolated from render-drift testing; and
factory/OpenSpec integration.

No TypeScript adapter, binding, consumer repository, Rust public API, crate dependency, target-support claim, release, or protocol behavior changes.

Local review

Local review: completed against the fresh origin/develop...HEAD diff.
Independent discovery review: Claude Code /review against PR feat(architecture): define language adapter mappings #509; six validator-completeness findings reproduced and resolved in one remediation round.
Findings resolved: version-window coherence, Rust-owned bound enforcement, malformed-table diagnostics, additive registry evolution, complete human rendering, redundant validation, mutation/render isolation, and deterministic Markdown whitespace.
Specialist review required/completed: architecture, compatibility, provenance, security/redaction, resource bounds, and maintenance reviewed locally.

Research and provenance

SDK-TS revision: 4bf86ebf69d5e96616a148e4c973f831f95fa38e, release line 8.1.4, Apache-2.0.
Rust reference revision: edf03abcc963d37703daa61192940394bdc553ca.
Exact SDK-TS DID, DID URL, parser, error, and test paths are retained in the machine registry.
The legacy DID URL shape is intentionally lossy because path arrays, a query Map, and a fragment string cannot preserve raw query order/duplicates or absent-versus-empty query and fragment state.
Both legacy parsing paths use InvalidDIDString; the mapping preserves distinct Rust codes did.invalid_did and did.invalid_did_url with caller-input redaction.

Constraints and limitations

Constraint impact: material.
Affected constraint IDs: SDK-ARCH-001, SDK-ARCH-002, SDK-SEC-003, SDK-DELIVERY-001, SDK-LIM-005, and SDK-LIM-006.
Effective versus target state: the mapping registry and validation become effective; generated adapters and consumer adoption remain target state.
Limitations: the seed covers only SDK-TS 8.1.4 DID/DID URL compatibility; Swift, Kotlin, bindings, consumer E2E, peer DID, credentials, DIDComm, and runtime mappings remain unsupported here.
Decision authority/activation path: issue architecture(bindings): specify canonical language adapter and error mappings #505 under parent milestone(A1): establish the shared compatibility foundation #504 and ADRs 0169, 0170, and 0173; protected develop PR.

Review and decomposition

Fresh-diff architecture, security, provenance, compatibility, and maintenance review completed with no unresolved blocker. The diff exceeds the generic 12-file/1,000-line attention threshold because the OpenSpec planning packet, canonical TOML registry, deterministic human projection, validator, mutation suite, and archive are one indivisible evidence contract. There is no production runtime code.

The initial local review fixed mutation/render evidence isolation and generated-Markdown whitespace. The independent discovery review then reproduced six validator-completeness gaps. One bounded remediation now parses and checks language-version windows, resolves adapter byte ceilings to public Rust constants, returns diagnostics for malformed nested values, permits additive conforming records beyond the required seed, renders every governed field, and removes a redundant error check. Mutation tests preserve each counterexample.

Validation

python3 scripts/check-language-adapter-mappings.py
python3 scripts/tests/language-adapter-mappings.py
python3 scripts/check-cross-language-vectors.py
python3 scripts/tests/cross-language-vectors.py
scripts/check-factory.sh .
scripts/factory ready establish-language-adapter-mappings
scripts/factory receipt establish-language-adapter-mappings
scripts/factory archive establish-language-adapter-mappings
nix flake check

All applicable aarch64-darwin checks passed. The local flake reports x86_64-linux as incompatible on this host; hosted fast provides the required Linux integration evidence.

Checklist

Closes #505

Signed-off-by: Yurii Shynbuiev <[email protected]>

Signed-off-by: Yurii Shynbuiev <[email protected]> # Conflicts: # scripts/check-factory.sh # scripts/tests/factory-contract.sh

Signed-off-by: Yurii Shynbuiev <[email protected]>

yshyn-iohk · 2026-09-30T09:07:23Z

Post-remediation verification found additional reproducible contract gaps, so this PR is intentionally returned to draft and is not merge-ready.

Blocking findings:

a symlinked parent directory can escape the repository and bypass canonical Rust byte-bound enforcement;
generated canonical Rust identifiers duplicate the crate prefix and treat stable error codes as Rust symbols;
field direction can contradict mapping direction; and
lossy error mappings do not have to name the lost distinction.

The same review also identified fixture extensibility and evidence-window gaps. Because the factory permits one automatic remediation round, these will not be patched silently in this PR. #510 captures one cohesive follow-up contract, including vector-catalog resolution now that #508 is merged.

Exact reviewed head: 7e0cbf76562f15f02761fcc839929afe9a94fde7
Exact green fast run: https://github.com/hyperledger-identus/sdk-rust/actions/runs/36691950241

yshyn-iohk · 2026-09-30T09:50:22Z

Follow-up #510 now has a frozen, validated planning contract and pre-implementation receipt on codex/fix/issue-510 (83a54607bce47336d2449057a0bddfffbc3ed27d). Implementation has not started.

This PR remains draft and blocked by the six verification gaps documented above. The intended path is a clean replacement PR to develop after #510 is implemented and independently reviewed; this PR should not be merged as-is.

Planning evidence: #510 (comment)

yshyn-iohk · 2026-09-30T12:58:06Z

Superseded by replacement PR #511.

The replacement carries the complete mapping baseline plus the independently reviewed #510 corrections, has green exact-head fast/policy/DCO/file-hygiene checks, and its final independent verification reported no blocking finding. This draft remains intentionally unmerged so the verified containment, identity, direction, loss, version, catalog, type, uniqueness, and lifecycle corrections cannot be bypassed.

## Summary - establish the canonical language-adapter registry and deterministic human rendering from the reviewed #509 baseline; - separate Cargo package, exact Rust API path, and stable public error identity; - reject traversal, symlink components, outside-root, non-regular, oversized, malformed, ambiguous, or weakened canonical-bound evidence; - enforce mapping/field direction compatibility and explicit structured losses; - restrict schema-v1 language compatibility to the pinned patch interval; - resolve mapping vectors exactly once against the canonical cross-language catalog while allowing shared evidence; and - make mutation fixtures discover every declared bound source and prove an additive fifth-language mapping. This is the clean replacement for draft #509. It changes no Rust runtime API, generated binding, language SDK, consumer repository, release, or publication behavior. ## Issue and decision record - Issue: #510 - Parent: #505 - ADR: ADR 0170 - OpenSpec change: archived as `2026-09-30-close-language-adapter-verification-gaps` - Base SHA: `644993c859b87e2da16612fcdf7cf1868cfe5981` ## Local review - Local review: completed; independent implementation review against `c6f52020abe4be9504d46dbcbaf218c7f631706f` found no blocking findings - Final exact-head delta: test assertion strengthening and OpenSpec archival only; locally reviewed against `224c1d4a3416a755f783a9f7a822131a565cfbb3` - Findings resolved: all six post-remediation #509 findings plus the three subsequent independent-review rounds - Deferred provenance hardening: #512 (non-blocking for metadata closure; required before adapter generation) ## Constraints and limitations - Constraint impact: material - Affected constraint IDs: SDK-ARCH-001, SDK-ARCH-002, SDK-SEC-003, SDK-DELIVERY-001, SDK-LIM-005, SDK-LIM-006 - Limitations: metadata and verification only; no adapter is generated or executed by this change - Decision authority: issue #510 and the accepted preimplementation receipt ## Evidence - focused validator: 4 canonical mappings passed - mutation suite: 2 positive and 90 negative cases passed - factory after archival: 104 passed, 0 failed - local Nix: all 38 compatible `aarch64-darwin` checks passed - `git diff --check`: passed - exact-diff review: no unresolved blocker - signed commits and DCO trailers: verified The OpenSpec change is archived and synchronized into the canonical specification. Exact-head hosted CI is the remaining merge gate. Closes #510 Closes #505 Supersedes #509 --------- Signed-off-by: Yurii Shynbuiev <[email protected]>

yshyn-iohk added 7 commits September 30, 2026 13:17

docs(architecture): specify adapter mappings

826d6e1

Signed-off-by: Yurii Shynbuiev <[email protected]>

chore(factory): record issue 505 preflight

d9d9cdb

Signed-off-by: Yurii Shynbuiev <[email protected]>

feat(architecture): add adapter mapping contract

22fcbbe

Signed-off-by: Yurii Shynbuiev <[email protected]>

chore(factory): sync issue 505 with develop

0ab2fb6

Signed-off-by: Yurii Shynbuiev <[email protected]> # Conflicts: # scripts/check-factory.sh # scripts/tests/factory-contract.sh

test(architecture): isolate adapter contract mutations

77bb85c

Signed-off-by: Yurii Shynbuiev <[email protected]>

docs(architecture): complete adapter mapping review

ba04457

Signed-off-by: Yurii Shynbuiev <[email protected]>

docs(architecture): archive adapter mapping contract

aa15559

Signed-off-by: Yurii Shynbuiev <[email protected]>

yshyn-iohk requested a review from a team as a code owner September 30, 2026 08:08

fix(architecture): harden adapter mapping contract

7e0cbf7

Signed-off-by: Yurii Shynbuiev <[email protected]>

yshyn-iohk mentioned this pull request Sep 30, 2026

architecture(bindings): close adapter registry verification gaps #510

Closed

11 tasks

yshyn-iohk marked this pull request as draft September 30, 2026 09:07

yshyn-iohk mentioned this pull request Sep 30, 2026

architecture(bindings): specify canonical language adapter and error mappings #505

Closed

8 tasks

yshyn-iohk mentioned this pull request Sep 30, 2026

fix(architecture): close adapter verification gaps #511

Merged

yshyn-iohk closed this Sep 30, 2026

Navigation Menu

Repository navigation

feat(architecture): define language adapter mappings - #509

feat(architecture): define language adapter mappings#509
yshyn-iohk wants to merge 8 commits into
developfrom
codex/feat/issue-505

yshyn-iohk commented Sep 30, 2026 •

edited

Loading

Uh oh!

yshyn-iohk commented Sep 30, 2026

Uh oh!

yshyn-iohk commented Sep 30, 2026

Uh oh!

yshyn-iohk commented Sep 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

yshyn-iohk commented Sep 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull request

Outcome

Issue and decision record

Factory contract

Scope

Local review

Research and provenance

Constraints and limitations

Review and decomposition

Validation

Checklist

Uh oh!

yshyn-iohk commented Sep 30, 2026

Uh oh!

yshyn-iohk commented Sep 30, 2026

Uh oh!

yshyn-iohk commented Sep 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

yshyn-iohk commented Sep 30, 2026 •

edited

Loading