docs(interop): composition matrix, recommended form, shared-key footgun (LAB-840)

[27Bslash6]

Closes LAB-840 (parent LAB-374).

Augments docs/features/interop-mode.md (created in #220) with the remaining usage material — verified against released 0.16.0 source, not guessed.

What's added

• Decorator-composition matrix — one row per form with the byte result: bare @cache, .production, .minimal, .secure all compose → spec-identical bytes (presets change runtime profile, never wire bytes; InteropSerializer is forced regardless of preset); .io composes in code but is gated on the saas#91 validator deploy; .local/backend=None rejected loudly (TypeError / ConfigurationError at decoration).
• interop= as a DecoratorConfig field on every entry point — bare, preset, and RORO forms, with @cache.production(interop=..., namespace=..., ttl=...) called out as the recommended form.
• The shared-entry footgun, prominently — its own section framing function-identity-free keys as the property that makes cross-SDK work: same (namespace, operation) + matching args share one entry including L1 (process-global, per-namespace). Operation names are a cross-team contract, like queue names.
• Encryption-mismatch warning (expert-panel CRIT): encryption config is part of the operation contract — a plaintext-config binder silently re-stores the value unencrypted at the shared key, defeating zero-knowledge; verified against _deserialize_interop.
• Integrity-checking nuance (panel MAJ hardened): integrity_checking has no effect under interop (no ByteStorage envelope to checksum), and unencrypted interop entries have no corruption detection at all — under .production just as .minimal. Reconciled with the existing "no metadata header" wording.
• Stale version line fixed — "Available since v0.12.0" (never on PyPI) replaced with a changelog pointer per the docs anti-drift lesson.

Verification

• All behaviour claims traced to source: config/decorator.py (field + preset **kwargs passthrough), decorators/intent.py + local_wrapper.py (.local rejection), decorators/wrapper.py:538-562 (L1-only/fast_mode guards), cache_handler.py:604-610 (integrity bypass), l1_cache.py:649-683 (process-global L1).
• pytest --markdown-docs docs/ → 121 passed, 0 failed. New executable blocks run honestly; notest only on blocks needing an undefined backend/db (per docs/CONTRIBUTING.md).
• Mandatory crypto/protocol gate: expert-panel-review run at high stakes (4 agents). Surviving findings applied (CRIT encryption-mismatch, MAJ zero-corruption-detection, 5 dedup/wording cuts); rejected "pin v0.13.0" — that version never hit PyPI, changelog pointer is the anti-drift fix.

Pre-existing README.md markdown-docs failures (cache undefined in fences) exist on clean main and are out of scope.

Summary by CodeRabbit

• Documentation
  • Updated interop mode documentation to reflect its released status.
  • Added guidance on supported decorator forms and preset behaviour.
  • Clarified operation naming, cross-function sharing, and encryption requirements.
  • Documented integrity-checking behaviour and risks when encryption settings differ.

[kodus-27b]

Code Review Completed! 🔥

The code review was successfully completed based on your current configurations.

Kody Guide: Usage and Configuration

Interacting with Kody

• Request a Review: Ask Kody to review your PR manually by adding a comment with the @kody start-review command at the root of your PR.

• Validate Business Logic: Ask Kody to validate your code against business rules by adding a comment with the @kody -v business-logic command.

• Provide Feedback: Help Kody learn and improve by reacting to its comments with a 👍 for helpful suggestions or a 👎 if improvements are needed.

Current Kody Configuration

Review Options

The following review options are enabled or disabled:

Options	Enabled
Bug	✅
Performance	✅
Security	✅
Business Logic	✅

Access your configuration settings here.

​

[coderabbitai]

Walkthrough

Changes

Interop mode documentation

Layer / File(s)	Summary
Document interop mode contracts docs/features/interop-mode.md	Updates the release status and documents decorator forms, shared operation naming, encryption configuration requirements, mismatch behaviour, and integrity handling.

Estimated code review effort: 1 (Trivial) | ~3 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description covers the change and verification, but it omits the template’s Motivation, Type of Change, and checklist sections.	Add the missing template sections, especially Motivation, Type of Change, Security Checklist, and Backward Compatibility.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title is concise and clearly matches the docs update around interop-mode composition, recommended forms, and shared-key warnings.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch lab-840-interop-doc-augment

---

_{Comment @coderabbitai help to get the list of available commands.}