Changelog

View Source

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Planning milestones vs Hex releases

This changelog uses Semantic Versioning headings like [0.1.0] for published Hex releases. Separately, maintainers track planning milestones labeled v1.0–v3.6 in .planning/MILESTONE-ARC.md and archived milestone evidence under .planning/milestones/ — those labels describe shipped tranches of work, not a second installable version axis on Hex (this repo remains 0.x on Hex until a real 1.0.0). When in doubt, treat .planning/MILESTONE-ARC.md as canonical for milestone ordering and archive paths.

Unreleased

Unpublished support claims

  • No new support claims have been cut after 0.2.1 yet. Future entries here must distinguish planning milestone work from published Hex release truth.
  • The companion-decoupling core refactor shipped in 0.2.0 (runtime :companions registry inversion — see the [0.2.0] section below).
  • The current published Hex family includes crosswake 0.2.1, crosswake_sigra 0.1.3, crosswake_chimeway 0.1.0, and crosswake_threadline 0.1.0. The local release graph also tracks crosswake_rulestead 0.1.0 and crosswake_rindle 0.1.0; public registry presence is reported by mix crosswake.release.status --live, and compatibility floors remain documented in guides/companion_compatibility.md.

Verification-required and advisory surfaces

  • Storefront, provider, device, checked-in native host, and optional companion proof lanes remain visible as advisory or verification-required evidence. They are not equivalent to fully supported native runtime breadth.
  • Provider/device sandbox proof remains advisory unless promotion criteria pass.

Deferred non-shipped claims

  • RevenueCat provider adapter, Chimeway notification delivery execution, native device/emulator proof lanes, and broad native runtime expansion beyond the listed live companion packages are not shipped in the published core Hex package. They stay routed to future milestones and must not be promoted without provider/native proof.
  • Future companion or native breadth still requires its own release, proof, and support-matrix update. Existing live companion packages do not promote RevenueCat, push delivery execution, physical-device evidence, or broad native runtime expansion.

Published Hex truth

  • The current published Hex release is 0.2.1. Public readers should treat this [Unreleased] section as future development and planning continuity, not a newer installable release.

[0.2.1] — 2026-09-14

Published release. Patch release over 0.2.0 carrying the Phase 154 control-surface, bridge-dispatch, and installer work below. The manifest_schema_version compatibility bump it contains is additive and native-inert.

Upgrade Impact

compatibility-bump only

manifest_schema_version moves 1.0.0 -> 1.1.0 (Phase 154, CTRL-05): Capability gains a required interaction field (:fire_and_forget | :device_answer | :user_answer) and @enforce_keys now requires both :rebuild and :interaction, making a control without a declared rebuild and interaction class unconstructable at compile time. This is additive and native-inert — the iOS and Android shells decode neither field — so no native rebuild is required for already-compatible adopters; the compatibility fixtures continue to fail closed on genuine mismatches.

Security

  • Content-Security-Policy hardening, not a cleanup (Phase 154, HRDN-01). Bridge dispatch no longer renders a server-built payload into an inline <script> element. The shipped CrosswakeBridge hook is an external module file (priv/static/crosswake.esm.js, served by the endpoint's static plug), which needs no script-src 'unsafe-inline' allowance; the Phoenix.HTML.raw <script> IIFE it replaces required either 'unsafe-inline' or a per-render nonce for every page that dispatched a control. Both showcase LiveViews migrated together, and a merge-blocking structural sweep asserts no module anywhere in the reference host renders raw HTML into a script element for bridge dispatch. A host that adopted the previous inline pattern by copy-paste can drop that allowance once it moves to Crosswake.Bridge.push/3.
  • Deleted examples/phoenix_host/assets/js/app.js, which carried a threat-mitigation comment for a boundary it did not implement. It was never served, used a message-handler name neither shell registers, and its message shape shared no fields with the bridge wire contract — a false security claim in an evidence-first repository.

Added

  • Crosswake.Bridge.dispatched/2 returns the wire envelope push/3 actually built for a given ref, so an adopter rendering evidence of a dispatch reads it back from the seam instead of hand-assembling a second copy that is free to drift from the manifest. It is a pure read and not an availability predicate — push/3 still always resolves to exactly one typed reply regardless of what it returns.
  • The host-owned policy module generated by mix crosswake.install now defines manifest/0, the call guides/install.md already documented for Crosswake.Bridge.attach/1.
  • mix crosswake.doctor now discovers the router from the install manifest and supports an explicit pre-shell posture with --native-targets none; automatic mode treats a host with no generated native shell as not claiming native support instead of failing on absent native proof hooks.

Fixed

  • mix crosswake.install derives the web namespace from the router's actual defmodule, preserving mixed-case names such as AcmeShopWeb instead of reconstructing them from the OTP application name.
  • The generated router import block excludes Phoenix.LiveView.Router.live/2,3,4, consumes the policy module attribute without a compiler warning, and adds the lexical Crosswake exclusion required by the standard Phoenix live_dashboard block.
  • Generated install manifests and runtime manifests report the Crosswake dependency version rather than the host application's version.

Documentation

  • Documentation-only: add an architecture guide and source walkthrough with accessible light/dark Mermaid diagrams and the Crosswake docs favicon. This adds no runtime API or support claim.
  • Document the mixed-host boundary: same-origin paths short-circuited to a reverse proxy are outside Phoenix route policy and the Crosswake manifest during the proxy-only phase; explicit manifest ownership for non-Phoenix routes remains unsupported.
  • Document the external bridge module's required host esbuild flags and the installer/doctor pre-shell day-one flow.

0.2.0 — 2026-07-03

Published release. Additive, non-breaking core API since 0.1.2 that the v17.0 first-party companion packages depend on.

Upgrade Impact

core-only/no native rebuild

Additive, Elixir-only core surface: Crosswake.Shell.Finding gains code and details fields, route policy gains an :auth clause, and the runtime :companions registry now drives the auth, notification, support-matrix, and doctor coupling sites through optional @behaviour callbacks (function_exported?/3) instead of compile-time coupling. Module names are preserved and the sole adopter touch-point (config :crosswake, :companions, [...]) is unchanged, so no native rebuild or adopter code change is required. manifest_schema_version, bridge_protocol_version, native_runtime_version, and capability majors are unchanged.

Added

  • Additive Crosswake.Shell.Finding code and details fields and an :auth route-policy clause — surface consumed by the first-party companion packages; existing adopter code is unaffected.
  • Runtime :companions registry inversion: the core auth, notification, support-matrix, and doctor coupling sites now dispatch to registered companions via optional behaviour callbacks, decoupling core from any specific companion at compile time.

Notes

  • This core release is the published prerequisite for the v17.0 first-party companion packages (crosswake_sigra, crosswake_chimeway, crosswake_threadline), which publish separately and require crosswake ~> 0.2 (>= 0.2.0). Current companion versions are tracked in [Unreleased] and guides/companion_compatibility.md.
  • Deferred and not shipped (unchanged from 0.1.2): RevenueCat provider adapter, Chimeway notification delivery, native device/emulator proof lanes, and broad native runtime expansion beyond the published-core shell path.

0.1.2 — 2026-06-17

Published release. Bundles the installable changes since 0.1.0, including work briefly carried as an internal 0.1.1 version bump that was never published.

Upgrade Impact

native or companion rebuild required

This release publishes the reusable iOS and Android shell-core packages to SwiftPM and Maven Central, adds release-time clean-room proof jobs, and extends compatibility-contract gating. Adopters integrating the generated native shell scaffolds must rebuild and resubmit their native host apps.

Lower-impact changes bundled in this release (no native rebuild needed):

  • core-only/no native rebuild — Threadline request-correlation observability (Crosswake.Plug.Threadline, Crosswake.Live.Threadline), structured telemetry, and mix crosswake.threadline docs-contract task are Elixir-only additions inside the existing contract axes; no native rebuild required.
  • core-only/no native rebuild — mix crosswake.doctor publish-readiness checks (--check-publish), expanded ExDoc guide set, and provider adapter seam contract vocabulary are Elixir-side additions; no native rebuild required.

Added

  • Published native shell core distribution path: generated iOS scaffolds resolve github.com/szTheory/crosswake-shell-core-ios through SwiftPM, generated Android scaffolds resolve io.github.sztheory:crosswake-shell-core-android through Maven Central, and both coordinates derive from the Crosswake package version.
  • Release-time clean-room proof jobs for iOS and Android that scaffold outside the monorepo and run swift build / gradle build against the just-published artifacts.
  • A merge-blocking published-dependency parity guard in mix crosswake.doctor --check-publish so generator templates cannot drift back to monorepo paths, placeholder orgs, or mismatched versions.
  • Threadline request-correlation observability: a stable correlation id propagated across the Plug pipeline (Crosswake.Plug.Threadline), the LiveView lifecycle (Crosswake.Live.Threadline), and bridge command envelopes, with structured telemetry (Crosswake.Threadline.Telemetry, Crosswake.Threadline.Id) and a mix crosswake.threadline docs-contract task. Surfaced through mix crosswake.doctor and the support matrix.
  • Compatibility-contract and support-matrix refinements, including bridge-protocol-version and commerce-corridor-version gating in route compatibility checks.
  • Provider adapter seam contracts only (StoreKit / Play Billing adapters remain out of scope — the seam vocabulary and entitlement-lane semantics are operationalized, not the providers).
  • Expanded ExDoc guide set shipped in the package (guides/): adoption, install, compatibility, support matrix, native shell, commerce, companions, threadline, Android UAT, and user-flow guides.
  • mix crosswake.doctor publish-readiness checks (--check-publish) covering Hex metadata parity and CHANGELOG/release truth.

Notes

  • The v9.0 brand system (brandbook/ — brand book, design tokens, logo suite, collateral, and the COLL-05 automated brand-verification suite) was developed in this window but is excluded from the Hex package (:exclude_patterns: ["brandbook"]), so it is not part of this installable release.
  • Deferred and not shipped in 0.1.2: RevenueCat provider adapter, Chimeway notification delivery, native device/emulator proof lanes, companion extraction, and broad native runtime expansion beyond the published-core shell path.

0.1.0 — 2026-05-29

Upgrade Impact

native or companion rebuild required

This is the initial published release. Adopters adopting Crosswake for the first time must scaffold and build their native host shells using the generated iOS and Android shell-core project templates. The route policy DSL, bridge contract, offline semantics, and commerce corridor declarations all require native shell code to activate native routes and capabilities.

Added

  • Route policy DSL for declaring per-route runtime ownership: LiveView, offline island, native screen, or adapter. Runtime manifest and compatibility contract generated from route policy declarations.
  • Bounded bridge contract for low-frequency native capability families (haptics, share, app_info, deep_link, permissions.status, notification_token, file_picker) with route-local enforcement and typed command envelopes.
  • Offline semantics: cached read-only routes, offline islands with append-only journals, sync endpoints, and server-authoritative reconciliation — each with explicit contract boundaries and doctor diagnostics.
  • Commerce corridor declarations with provider-neutral commerce.corridor.* denial vocabulary, entitlement lifecycle lane semantics (authority/access/reconciliation/freshness/evidence), and a Phoenix-owned reconciliation inbox example. Provider adapters (StoreKit, Play Billing) are not included; this release operationalizes the seam contract only. There are no first-party companions yet.
  • mix crosswake.doctor diagnostics, support matrix, and proof lanes verified against three adopter-shaped exemplar lanes: Phoenix SaaS portal, selective-native flow, and local-first study flow.

Roadmap traceability

Internal planning milestones v1.0 (Route Policy Foundation), v2.0 (Adopter Stress Profiles), v3.0 (Capability Contract And Packaging), v3.1 (Native Capabilities and Bridge Expansion), and v3.2 (Commerce And Entitlement Seams) are archived in .planning/MILESTONES.md. These are not separate Hex releases. See .planning/PROJECT.md for overarching goals.