@khipu/bridge-contract

The published, versioned artifact of the khipu JS↔native bridge contract — the web seam. It exposes the public TypeScript surface that the always-live web client (kws.js) uses to type its bridge invocations against the slow-updating native SDK, so the two evolve compatibly via existence-checks + a contract_version string (FR7, FR12-CONTRACT), never version pins.

What it exports

• Public error model (snake_case, AC-BRIDGE-015/016/017): KhipuPaymentError, KhipuPublicErrorCode, KhipuErrorFault, ErrorTranslation, and the pure helpers translate, faultOf, publicError.
• DiagnosticsDump shape (AC-BRIDGE-018): DiagnosticsDump, WebViewEngine, PendingOperation, RecentError, CapabilityLatency — the dumpDiagnostics() response contract.
• CONTRACT_VERSION (AC-BRIDGE-022): the contract version string (== envelope_version for v1).

The public surface carries no raw correlation_id (only the hashed correlation_id_hash) and no __internals__ — tsconfig.publish.json emits a .d.ts that excludes the internal trees, and a governance gate (bridge/codegen) fails the build if either leaks.

The types are generated — do not edit

src/types/public/errors.ts and src/CONTRACT_VERSION.ts are generated by bridge/codegen (do-not-edit, @generated header). To change them, edit the codegen source and run make codegen. The barrel src/index.ts is the only hand-written file. The contract_hash of the schema bundle stays frozen — this package consumes the generated surface, it does not regenerate or alter it.

Build

npm run typecheck   # tsc -p tsconfig.json  (strict, no emit)
npm run build       # tsc -p tsconfig.publish.json  -> dist/ (.d.ts + .js, __internals__ excluded)

The toolchain is the frozen typescript ^5.6.0 already used by bridge/codegen — this package adds 0 runtime dependencies (NFR7). The authoritative package-shape check runs in the codegen test harness (bridge/codegen/src/test.ts): it compiles this package and asserts the emitted .d.ts exports the public types and contains no __internals__ / no raw correlation_id.

[NOTE FOR PM] — who depends on this, and the release order

Future cross-platform plugins (React Native / Flutter / KMP) consume this package for typed bridge invocations, but they depend on the native SDK, not directly on the bridge contract — v1 does not support those plugins directly (architecture.md:391). This package types the seam; the SDK ships the behavior.

Distribution is serial-gated (AR23, architecture.md:377,1797): the release order is npm first (@khipu/bridge-contract), then the Android AAR, then the iOS framework — each downstream artifact pins the version published just before it, so a fielded native build and a live web build always agree on the contract.

Forward-looking — not built here. Story 1.9 makes this package buildable + packable (npm pack, .d.ts shape asserted) only. The real npm publish + the AAR/iOS-framework serial-gated release CI is Epic 7 (Story 7.3), which owns the release infrastructure. Do not publish from this story.