Crosswake Capability Families

View Source

Crosswake does not present capabilities as a generic plugin catalog. It classifies candidate native affordances by who should own the route interaction loop, then states the support posture honestly.

Ownership-First Rubric

Start with the route owner, not the API shape.

  • bounded_bridge = Phoenix-owned route, low-frequency semantic request/reply action, no native authority over the interaction loop
  • native_screen = native code owns permission choreography, capture or scan session, or policy-sensitive UI loop
  • backend_seam = Phoenix/backend remains the control plane and route-local bridge calls do not own truth
  • defer = outside current thesis, support posture, or proof budget

Use bounded_bridge only when the route stays Phoenix-owned and the native side is answering one narrow semantic request. Use native_screen when native code must run the session. Use backend_seam when backend truth or provider coupling is the real seam. Use defer when Crosswake would have to widen its thesis or support claims to act like a generic mobile framework.

Capability Families

Capability families are public vocabulary. Bridge commands are subordinate protocol details.

The first Phase 11 inventory is:

  • deep_link
  • app_info
  • haptics
  • share
  • file_picker
  • permissions.status
  • notification_token
  • media_capture
  • scanner
  • document_scan
  • paywall_entry
  • purchase_intent
  • restore_intent
  • entitlement_snapshot
  • reconciliation_evidence

deep_link remains manifest-first shell activation truth, not route-local bridge or navigation authority. Route DSL declarations should use semantic family ids such as app_info, haptics, share, permissions.status, notification_token, and file_picker. Transport commands like app.info.get, haptics.impact, share.invoke, and files.pick remain protocol details rather than the public route-policy vocabulary.

Bounded Bridge

bounded_bridge families keep the route Phoenix-owned. Crosswake may expose one typed request/reply seam, but the shell does not become navigation authority, session authority, or backend truth.

Representative bounded-bridge families:

  • app_info
  • haptics
  • share
  • file_picker when bound to a declared transfer_id and returning copy-first staged-handle items that stay transfer-verified evidence rather than durable file authority
  • permissions.status when treated as a read-only snapshot of the notifications alias only
  • notification_token when treated as a prompt-free, provider-explicit evidence snapshot rather than delivery truth

file_picker keeps the route Phoenix-owned only when it stays subordinate to an inbound source: :native_picker transfer seam. The public success shape is transfer_id plus items, metadata fields other than handle may be null, and cancelation is a distinct typed outcome instead of items: [].

This is the only transfer-backed bounded-bridge exception. Ordinary bounded bridge families authorize through the declared family alone; file_picker also requires the matching transfer_id and native_picker seam.

Native Screen

native_screen families move the interaction loop into native ownership because the route needs native session control, permission choreography, or platform-sensitive UI fidelity.

Representative native-screen-first families:

  • media_capture
  • scanner
  • document_scan

Backend Seams And Deferred Surfaces

Some surfaces are valid capability-family vocabulary without being honest Phase 11 core support claims.

  • paywall_entry, purchase_intent, restore_intent, entitlement_snapshot, and reconciliation_evidence are meaningful taxonomy entries, but entitlement truth remains backend-owned and provider/store boundaries stay explicit.
  • Control-plane or provider-heavy surfaces belong in backend_seam posture rather than route-local bridge authority.
  • Families that would force broad scanner, storefront, or review-heavy support claims stay deferred until Crosswake can prove them honestly.

Commerce Boundaries

  • paywall_entry, purchase_intent, restore_intent, entitlement_snapshot, and reconciliation_evidence are core contract vocabulary
  • StoreKit, Play Billing, RevenueCat-style SDK glue, provider verification clients, webhook helpers, and native purchase command/event contracts are companion
  • silent web checkout or generic WebView fallback for digital goods is unsupported

Commerce Corridor Ownership Guidance

  • paywall_entry and account_management stay Phoenix-owned corridor surfaces.
  • purchase_intent and restore_intent require native-screen or companion corridor posture before activation.
  • Provider adapters remain out of scope in Phase 19; this guide documents ownership and fail-closed posture, not adapter implementation.

Family Naming Rules

  • Use stable semantic family names, not generic buckets like device, media, or plugins.
  • Keep family ids public and small.
  • Keep bridge commands lower-level and operation-shaped.
  • Do not let package class override route ownership.

Package Boundary Rules

  • core = semantic family is low-frequency, typed, route-local, and supportable without provider-specific native package sprawl
  • companion = family needs extra native/package choreography, backend/operator coupling, or release-boundary pressure beyond core
  • example/docs-only = family is useful for guidance and classification, but Crosswake is not claiming first-class shipped support yet
  • defer = family is outside the current thesis, proof budget, or honest support posture

Package class does not override runtime ownership. A family can still be native_screen and companion, or backend_seam and example/docs-only.

Packaging Ledger

Crosswake keeps one primary public package: crosswake. Package class explains release burden and support posture; it does not override route ownership.

  • core = the default crosswake package and its bounded contract surfaces
  • companion = explicit first-party extensions when native churn or provider coupling exceeds core
  • example/docs-only = guidance surfaces that teach boundaries without becoming runtime packages
  • defer = surfaces intentionally withheld until release choreography and proof stay honest

Read guides/support_matrix.md for the generated packaging ledger rendered from canonical support truth.

Documentation Strength

Crosswake distinguishes three public documentation strengths:

  • supported example
  • companion guidance
  • docs-only classification

Use these labels literally. They tell adopters whether they are reading proof-backed artifact guidance, future companion boundary guidance, or classification material that is not first-class shipped support.

Docs-Only Boundary

Docs-only surfaces are not first-class supported. They are useful because they make route ownership, denial behavior, fallback behavior, prerequisites, and rebuild pressure explicit before Crosswake widens support claims.

  • Checked-in example hosts and install walkthroughs are product surfaces, but they are not runtime package boundaries.
  • Docs-only material must link back to guides/support_matrix.md.
  • Runnable docs-only lanes are disallowed. Promotion requires reclassification plus proof and support-matrix updates.
  • Graduation criteria must say what proof, release policy, and rebuild posture would be required before support expands.

Route owner

paywall_entry, purchase_intent, restore_intent, entitlement_snapshot, and reconciliation_evidence remain Phoenix/backend-owned seams. A docs-only classification does not authorize the device to own entitlement truth.

Why not core/companion

These surfaces are meaningful vocabulary now, but provider/storefront churn, reviewer guidance, and backend reconciliation burden are still too high to market as first-class runtime support.

Host-owned responsibilities

The host owns storefront/provider selection, backend reconciliation, receipt or event ingestion, and explicit native-screen decisions when policy-sensitive purchase UI cannot stay Phoenix-owned.

Prerequisites

Backend entitlement authority, provider-specific adapter design, storefront guidance, and explicit support-matrix classification must exist before promotion.

Denial behavior

If the seam is undeclared or unsupported, Crosswake fails closed with explicit unavailable posture instead of pretending the bridge or shell can complete a purchase flow safely.

Fallback behavior

Fallback remains Phoenix-owned guidance or a deliberate native-screen requirement. Crosswake does not imply a runnable supported host recipe from docs-only examples.

Native rebuild required

Usually yes once a real storefront adapter or native provider SDK enters the picture. Docs-only classification by itself does not require a rebuild because it is guidance, not shipped runtime support.

First Public Example Set

Crosswake keeps the first example set narrow and exemplar-aligned:

  • deep_link, app_info, haptics, share, paywall_entry, purchase_intent, restore_intent, entitlement_snapshot, and reconciliation_evidence are the first canonical core examples.
  • permissions.status, file_picker, media_capture, notification_token, rollout, and audit are the first boundary-heavy examples after the base bridge families.
  • auth remains example/docs-only guidance until its backend/session seam is proven.
  • scanner and document_scan are explicit defer examples for now.

Package Class Examples

  • core: deep_link, app_info, haptics, share, file_picker, permissions.status, paywall_entry, purchase_intent, restore_intent, entitlement_snapshot, reconciliation_evidence
  • companion: media_capture, notification_token, rollout, audit
  • example/docs-only: auth
  • defer: scanner, document_scan

Explicit Defers

scanner and document_scan stay deferred because they imply heavier native ownership, policy burden, and broader proof/support-matrix breadth than Crosswake can honestly claim today.

Reviewer/Storefront Notes

When adopting native capabilities, especially native_screen ones, you must prepare explicit reviewer notes for App Store and Play Store submissions. Reviewers will check whether your requested capabilities (e.g., haptics, media capture, permissions) match the app's core functionality. If your Crosswake app requires a capability, you must provide a clear reviewer playbook demonstrating the flow.

Fallback Behavior

Crosswake requires explicit fallback behavior for any declared capability.

  • If a capability is undeclared, unavailable, or denied by the bridge, the route must gracefully degrade.
  • Fallback typically involves returning to a Phoenix-owned baseline (e.g., showing a standard web upload form instead of a native media capture screen, or standard UI state without haptics).
  • Never fail open. If a required native interaction is missing, the route should remain bounded and explicit about its failure state.