// SPDX-License-Identifier: CC-BY-SA-4.0
// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath)
= CappauScripto Compatibility Matrix
:toc:
:toclevels: 2
:icons: font

== Scope

This matrix tracks CoffeeScript-idiom compatibility for CappauScripto.

Related documents:

* link:CAPPAUSCRIPTO-FACE-IDENTITY-CARD.adoc[Face Identity Card]
* link:CAPPAUSCRIPTO-RELEASE-GATE-TRACKER.adoc[Release Gate Tracker]
* link:CAPPAUSCRIPTO-MIGRATION-SPEC.adoc[Migration Spec]

Important:

* This document is a target matrix until runtime evidence links are attached.
* Status MUST move from target to measured before a launch claim.

== Status Legend

* `V1-Required`: must be fully supported for first public launch.
* `V1-Partial`: acceptable for launch with documented caveats.
* `V2-Deferred`: intentionally postponed.
* `Blocked`: cannot proceed without core changes or design decision.

== Core Language Idioms

[cols="1,2,1,2,2", options="header"]
|===
| ID | CoffeeScript idiom | Status | Notes | Evidence hook

| CM-01
| Significant indentation blocks
| V1-Required
| Core readability contract of the face.
| TODO: parser fixture set

| CM-02
| `->` function shorthand
| V1-Required
| Must preserve concise function authoring.
| TODO: transform fixture + emitted IR snapshot

| CM-03
| `=>` lexical `this`
| V1-Required
| Must preserve lexical binding behavior in nested scopes.
| TODO: behavioral test suite

| CM-04
| Optional parentheses for calls
| V1-Required
| Must parse reliably without introducing ambiguity regressions.
| TODO: parser ambiguity suite

| CM-05
| Postfix conditionals (`run() if ok`)
| V1-Required
| High-frequency idiom in CoffeeScript codebases.
| TODO: syntax + lowering fixture

| CM-06
| `unless` condition form
| V1-Partial
| Prefer support; may lower to canonical `if not`.
| TODO: style and linter rule decision

| CM-07
| Ranges (`[a..b]`, `[a...b]`)
| V1-Required
| Inclusive/exclusive semantics must be explicit and test-covered.
| TODO: range semantics tests

| CM-08
| Comprehensions with guards
| V1-Required
| Map/filter lowering must preserve order and side-effect boundaries.
| TODO: comprehension equivalence suite

| CM-09
| Existential operator (`?`) and soak (`?.`)
| V1-Required
| Null-safe behavior is central to migration comfort.
| TODO: null-safety regression tests

| CM-10
| String interpolation (`"#{x}"`)
| V1-Required
| Preserve interpolation semantics and escaping behavior.
| TODO: interpolation parser tests

| CM-11
| Destructuring with defaults
| V1-Required
| Required for idiomatic config and options patterns.
| TODO: destructuring fixture corpus

| CM-12
| Class sugar (`class X extends Y`)
| V1-Required
| Must lower to core object model without behavior drift.
| TODO: inheritance behavior tests
|===

== Module and Ecosystem Surface

[cols="1,2,1,2,2", options="header"]
|===
| ID | Area | Status | Notes | Evidence hook

| CM-20
| CommonJS interop (`require`, `module.exports`)
| V1-Required
| Essential for legacy CoffeeScript migration.
| TODO: CJS bridge fixture

| CM-21
| ESM interop (`import`, `export`)
| V1-Required
| Needed for modern JS ecosystem parity.
| TODO: dual-module fixture

| CM-22
| Source maps from face code to core output
| V1-Required
| Required for usable diagnostics and debugging.
| TODO: source-map fidelity test

| CM-23
| npm/pnpm/yarn workflow compatibility
| V1-Required
| Tooling home criterion requires package-manager parity.
| TODO: CI matrix runs
|===

== Known Caveats (Must Be Visible)

[cols="1,3,2", options="header"]
|===
| ID | Caveat | Mitigation

| CV-01
| Optional-call syntax can create parse ambiguities in dense chained calls.
| Prefer explicit parentheses where ambiguity is detected; autofix in `cappa migrate`.

| CV-02
| `unless` readability may degrade with nested boolean expressions.
| Lint recommendation to rewrite to `if not` for complex predicates.

| CV-03
| Comprehension side effects can hide ordering bugs in migrated code.
| Migration tool emits warning and suggests explicit `map`/`filter` rewrite.
|===

== Launch Exit Criteria

Compatibility can be declared launch-ready only when:

* all `V1-Required` rows have evidence links and passing results,
* no `Blocked` row is unresolved,
* caveats are mirrored in migration diagnostics and docs.
