feat: functional trusted VSI binding, ladder signing and ownership hardening

[mstattma]

Functional trusted VSI Python binding plus single-file ladder signing, paired with castlabs/c2pa-rs feat/trusted-vsi-functional.

What's in it

• TrustedVsiSession and helpers for the trusted native ABI; exact native gate c2pa-rs/0.92.0-dev + capability mask 63 (no version range). Contract: docs/trusted-vsi-python-contract.md.

• True merge of the ladder candidate 502b8bb2 (Builder.sign_ladder), with ladder callback errors aligned to the other Builder paths (DynamicAssertion exceptions keep identity; claim-signer interrupts propagate).

• True merge of the generic native-ownership patch 7ba8615: consume-first FFI calls triage registry rejections by the rejected handle id, with anchored tag parsing; opaque C2paStream. Opaque-registry-only checks in tests/test_native_ownership_opaque.py.

• True merge of its reviewed follow-up a303db8 (not the temporary CI-only commit): comments clarify deferred opaque-native drops and the sticky error slot; tests cover a real non-NULL typed pointer and distinguish the raised error from the slot after cleanup. Remaining real-native concurrency/sticky-slot checks and the stock Windows ARM64 ownership-qualification gap are tracked in docs/roadmap.md.

• Unreleased source/qualification identity 0.37.13.dev0. Immutable dev5 release inputs, lock and tooling unchanged.

• Paired CI native pin 6b506352 (203dc08d plus CI-only fixes in feat: functional trusted VSI (consolidated candidates + ContentAuth main) c2pa-rs#15; no C ABI change).

Qualification

• Hosted paired Linux + Windows (trusted_vsi_only, non-publishing), run 36808706395 at 12d265db, native 6b506352, Rust 1.96.0. Both platforms: 186 focused, real-native ladder harness, 730 non-threaded, 54 threaded, 186 installed-wheel tests passed. Previous pairing: run 36793704783 at 5c64f2c, native 203dc08d, identical counts.
• Local Linux against the exact native library: 263 focused tests and 45 subtests passed.
• Stock c2pa-rs 0.91.0 Windows x64 ownership/unit/ladder/threaded qualification passed separately in mstattma run 36775608167. Stock Windows ARM64 ownership qualification was outside that scope.
• Reviews: independent review of each delta; ladder owner review of callback/ownership changes.

Not in scope

No publication; the dev5 release path still refuses this source.

[mstattma]

@BibinBaby444 requesting your review (a formal review request isn't possible: you're not a collaborator on this repository). Companion draft PRs: castlabs/c2pa-rs#15, #4, castlabs/stardustproof-keystore#13, castlabs/stardustproof-c2pa-signer#25.

[mstattma]

The independently reviewed ownership follow-up a303db8 is true-merged (not cherry-picked) into functional head 5c64f2cc090eeb29506bc766faa69b959e4ed982; the CI-only commit remains excluded. The remaining native-registry checks and stock Windows ARM64 ownership qualification are in docs/roadmap.md. Paired run 36793704783 passed on Linux and Windows against native 203dc08d: 186 focused, real-native ladder harness, 730 non-threaded, 54 threaded, and 186 installed-wheel tests per platform. Stock 0.91.0 Windows x64 passed in mstattma run 36775608167. @BibinBaby444 please review the new merge abef446 and roadmap commits bc9e99d, 5c64f2c. No release or dev5 evidence was changed.

[BibinBaby444]

Changes requested. One memory-safety bug reachable from plain Python, plus one native state that's invisible to Python. Verified at 12d265db against a native built from c2pa-rs d738fbb2 (debug, unstable_live_video). Note that CI is not evidence here yet: every test job on this PR was skipped, including "Trusted VSI paired-source API"; only format and tooling checks ran.

P1: closing a session during a native call frees callbacks native is still using.

• TrustedVsiSession._release drops _signer_callback_cb, _dynamic_assertion_cbs and _trusted_vsi_callback, and _teardown calls it before c2pa_free.
• Native free defers the actual drop while a call holds the borrow, so the in-flight finalize_init_uuid keeps calling through the freed thunks.
• Once the Context has been closed (which the contract allows), the session holds the only reference to the claim-signer thunk.
• A single thread is enough. Close the session from inside its own signer_binding callback, then allocate fresh SignerCallbacks:

  finalize raised: _C2paSignature('Signature: internal error (bad parameter: signer callback returned error code -1)')
  real claim callback calls: []  impostor calls: [1876]
  

• Native jumped through the freed claim thunk into an unrelated callback, which received the 1,876-byte claim payload. With different reuse that's a crash or a call into arbitrary code.
• Suggest keeping the callback pins alive for the object's lifetime (don't clear them in _release), or deferring close() until in-flight calls drain.
• The same drop-on-close pattern exists in the older live-video VSI session and Builder _releases, and the native contract text ("until the handle is freed") should say "until the deferred drop".

P2: blocked is never exposed.

• Native C2paLiveVideoTrustedVsiStatusV1 has blocked: bool between has_exhaustion_reason and exhaustion_reason, at offset 18.
• The ctypes struct, TrustedVsiStatus and status() all omit it. The layout still lines up, since Python treats the byte as padding, so there's no memory hazard.
• But Python can't see the one state the contract tells adapters to act on ("After a failure once an external signing call began, the session is blocked. Discard it, construct a NEW session…"):

  before failure: native blocked byte[18] = 0  -> status() has no blocked field
  after failure:  native blocked byte[18] = 1  -> status() unchanged
  next call: _C2paOther Other: bad parameter: session is blocked after a failed external signing step; …
  

• Add the field and a blocked attribute on TrustedVsiStatus, update the offsets pinned in tests/test_trusted_vsi_api.py, and add a paired test that asserts status().blocked after a callback failure.

P2: the stock-native lane will fail, and CI hasn't run it. The dynamic variant of test_scripted_wrappers_store_base_exceptions_return_minus_one_and_reraise calls signer.add_dynamic_assertion unguarded. The -k "not paired" lane in build.yml downloads upstream c2pa-v0.91.0 (c2pa-native-version.txt), and v0.91.0 (e7cc666c) doesn't export c2pa_signer_add_dynamic_assertion, so those four parametrizations raise NotSupported. Guard the variant on has_dynamic_assertions() (or stub the export in _ScriptedNative), then get the skipped jobs to actually run.

P3

• Ladder error guidance drops a guarantee. docs/ladder-signing.md and the sign_ladder docstring say "Errors may leave partial newly created outputs; discard these files", but leave out native's guarantee that "Existing files, including every source, are never overwritten". The native error doesn't say which path failed, so say callers should delete only destinations they confirmed absent before the call. Otherwise a cleanup-everything handler deletes a pre-existing file.
• The version gate is a release label, not an ABI identity. 0.92.0-dev is upstream's workspace version, so the gate effectively rests on the symbol plus mask 63. A native ABI-revision probe would make a future in-place V1 struct change detectable.