API stability and hierarchy¶

1.0 compatibility baseline¶

1.2.0 is the current published stable production release. 1.0.0 established the immutable root-API compatibility baseline for the 1.x line, and qualified 1.1 additions remain module-scoped. Ten W1–W4 typed workflow routes are supported in eyetrajectoriespy.workflows; the separate E1–E4 helpers remain experimental.

ONE_DOT_ZERO_API_STABILITY.json is the immutable machine-readable contract generated from the qualified 1.0 stabilization programme. On the 1.x line it is checked as a frozen compatibility subset of the live package surface rather than being regenerated whenever an additive API is introduced.

The historical 1.0 public boundary contains 458 public exports. 455 are stable 1.x APIs and three remain explicitly experimental:

• conditional_transfer_entropy;
• discrete_transfer_entropy;
• return_map_stability.

The compatibility route fit_sparse_fpca_fdapy remains a stable public name; its backend-specific role is intentional and does not make it an accidental alias of native fit_sparse_fpca.

The contract is stronger than a namespace count. It freezes the exact 1.0 stable-name allow-list and cryptographic evidence for the historical 1.0 namespace, callable signatures and result-container schema fields. A frozen export disappearing, a frozen stable signature/result schema drifting, or the reviewed experimental/compatibility classifications changing is a hard failure. Additive post-1.0 exports are allowed under SemVer, but they are reported explicitly by CI and are not inserted retroactively into the immutable 1.0 manifest.

No deprecation or removal was introduced by the 1.0 stabilization programme. Final 1.0.0 was published on 4 October 2026 after literal-version qualification and production observation; post-publication readiness was then disarmed again.

The completed path was:

The observational predecessor is PUBLIC_API_1_0_AUDIT.json; the exhaustive installed inventory is generated by scripts/audit_public_api_surface.py. scripts/freeze_one_dot_zero_api.py can still generate a live public-surface observation, while its compatibility mode verifies that the immutable 1.0 boundary remains intact and reports any additive 1.x exports separately.

1.1 and 1.2 module-scoped additions¶

The stable 1.1 sparse/irregular additions are documented in the 1.1 module API. The published 1.2 workflow contracts remain under eyetrajectoriespy.workflows, with no root-namespace promotion; see transparent orchestration and the machine-checked WORKFLOW_API_AUDIT.json in the repository. The candidate source does not imply publication.

Public API levels¶

Canonical¶

Recommended default entry points for common scientific questions. The five canonical routes are declared in CANONICAL_WORKFLOWS.json and documented in the canonical workflow guide.

Advanced¶

Supported and tested APIs for a more specific scientific need after the canonical route is understood. Examples include sparse PACE FPCA, phase analysis, full-refit mixed-effects bootstrap and exposure-aware generalized prediction.

Diagnostic¶

Inspection, sensitivity and audit APIs. They expose consequences of declared choices but must not silently select the preferred model/specification. Diagnostic status does not weaken name/signature stability once an API is in the frozen stable boundary.

Experimental¶

Supported code with a narrower validation or interpretation boundary. The three experimental functions named above remain public and tested, but are outside the 1.0 compatibility guarantee. Any future change to their stability treatment requires an explicit governance decision; it does not rewrite the historical 1.0 evidence retroactively.

Supported 1.1 module-scoped additions¶

The post-1.0 sparse/irregular programme adds specialized APIs without mechanically expanding the package-root namespace. These module-scoped imports are supported 1.1 surface, not private implementation details. See the formal 1.1 module API and integration audit.

The root decision is deliberate: module paths make specialized scientific contracts visible while the immutable 1.0 root boundary remains easy to distinguish. A future root re-export would be an additive API decision requiring explicit review; it is not implied by support for the module path.

Naming conventions for new APIs¶

New public APIs should follow these conventions unless a scientific object requires a clearer domain name:

• estimators: fit_*;
• resampling procedures: bootstrap_* when the operation is genuinely a bootstrap;
• plotting helpers: plot_*;
• tidy/tabular extractors: *_frame;
• manuscript wording: *_reporting_text;
• stochastic control: random_state;
• interval level: confidence_level;
• hierarchy identifiers: participant_column and trial_column where those concepts apply;
• result containers: descriptive CamelCase names ending in Result when the object represents the result of an analysis rather than a data container.

These are forward conventions, not grounds for mass-renaming established APIs. After 1.0, a proposed new public API must make an explicit stability-status decision rather than entering the stable set implicitly.

1.x compatibility rule¶

The completed post-0.12 evidence showed that the non-experimental public surface has coherent roles, workable end-to-end ergonomics, reproducibility/serialization evidence, and no demonstrated scientific omission requiring an immediate breaking change. That evidence underpins the current 1.x promise.

The live 1.x namespace may therefore be a strict superset of the 1.0 namespace. The dedicated compatibility gate requires every frozen 1.0 export to remain available, preserves the frozen stable signature/result-schema digest, rejects duplicate public names, retains the reviewed experimental and compatibility classifications, and prints any new live exports explicitly. New 1.x APIs receive their own review and evidence; they do not mutate the historical 1.0 manifest.

Test coverage alone is not sufficient. Age alone is not sufficient. Visual symmetry across result objects is not sufficient. The frozen contract is not a scientific claim that every API is equally important; it is a compatibility boundary.

Versioning should follow this posture:

• 1.0.x — compatible bug fixes, documentation, portability, validation and performance improvements that preserve established scientific meaning;
• 1.x — additive capabilities or deliberately governed compatible extensions;
• 2.0 — breaking stable API or scientific-contract changes after explicit deprecation, except when an exceptional correction is necessary to prevent demonstrably wrong scientific results.

Plotting stability rule¶

Every public plot_* API must remain represented by one deterministic documented gallery case. This is a documentation contract, not a requirement to manufacture a plot for every result object.

Deprecation window¶

A stable 1.x public API scheduled for eventual removal should remain available for at least two subsequent minor releases after the replacement is introduced, unless retaining it would cause incorrect scientific results or a security defect. Scientific-correctness exceptions must be documented explicitly.

A future rename must:

1. introduce the canonical name before removing the historical name;
2. keep an explicit compatibility alias during the deprecation window where technically possible;
3. emit a targeted DeprecationWarning that names the replacement;
4. update examples, mathematical contracts and reporting documentation in the same change; and
5. document the earliest eligible removal release.

Deprecation is not an excuse to reinterpret an existing result object silently. Changes to estimands, units, resampling units, clustering, denominator/exposure semantics or uncertainty definitions require a new explicit contract.

No deprecation or removal is currently authorized by the 1.0 compatibility baseline.

Historical stabilization decisions¶

Earlier stabilization work established the current hierarchy without removing public statistical APIs. Historical names that do not perfectly match the forward conventions remain available; established descriptive operations such as recurrence_matrix(), rqa_metrics(), dynamic_time_warping_distance() and register_to_landmarks() are not mechanically renamed.

The native sparse-FPCA transition deliberately used replacement-by-addition:

• fit_sparse_fpca_fdapy() remains the explicit compatibility backend;
• fit_sparse_fpca() is the separate native estimator;
• the native function is not a hidden call into FDApy; and
• coexistence alone is not grounds for deprecating the compatibility route.

The same distinction applies between common-grid fit_mfpca() and native sparse paired-planar fit_sparse_mfpca(): they represent different observation contracts, not duplicate spellings of one analysis.

Argument consistency¶

The project audits but does not globally reorder historical signatures. New APIs should keep required scientific objects positional only when their meaning is unambiguous and place analysis choices behind keyword-only arguments where possible.

Existing defaults remain unchanged unless a documented correctness issue requires otherwise. Frozen 1.0 stable callable signatures and result-container fields are included in the compatibility digest, so an incompatible edit to a frozen stable API cannot pass the dedicated 1.0 API-stability gate silently.

Failure semantics¶

Canonical workflows prefer explicit failure to silent repair. In particular, the package should not silently:

• interpolate or convert missing values to zero;
• choose a model, family, correlation structure or sensitivity winner;
• infer grouped-binomial denominators or Poisson exposure;
• drop failed bootstrap refits;
• reinterpret participant/trial independence;
• clip scientifically meaningful uncertainty merely to satisfy physical bounds;
• or hide nonportable scientific state during serialization.

The frozen/root 1.0 surface remains in the Public API reference. Supported post-1.0 module-scoped additions are listed separately in the 1.1 module API. The exhaustive capability list is separate from the recommended entry paths. The post-0.12 consistency audit records the historical evidence that preceded the 1.0 boundary freeze.