# Naming & aggregate facade (LOCK-GOV)

This page records the governed naming of the portable aggregate and the
**additive** import facades introduced by the first `LOCK-GOV` slice. It is the
Python-facing companion to the ecosystem governance decisions (`GOV-003`
per-language source-of-truth names, `GOV-004` alias/token policy).

## Aggregate package names (current, RC V1)

The aggregate is published under the bare `nirs4all` name in every host language
**except Python**, where the full `nirs4all` modelling library already owns that
import root. To avoid colliding with it, the Python aggregate ships as
`nirs4all-core` (canonical import `nirs4all_lite`).

| Target | Distribution / external name | Import / module name |
| --- | --- | --- |
| Python | `nirs4all-core` | `nirs4all_lite` |
| Rust | `nirs4all` | `nirs4all` |
| JavaScript/WASM | `nirs4all` | `nirs4all` |
| R | `nirs4all` | `library(nirs4all)` |
| MATLAB/Octave | `nirs4all` | `+nirs4all` namespace |

## Applied: `nirs4all-lite` → `nirs4all-core` (RC V1)

The governance direction promoted the aggregate from `lite` to
**`nirs4all-core`** (SW2 `GOV-003`, A13 `DEC-GOV-002`, RC V1 control board).
This is a *concept* rename, **not** a single literal rename across ecosystems:
Rust/npm/R/MATLAB already use the bare `nirs4all` name and are unaffected. Only
the Python distribution name changed.

The RC V1 head applies the rename in package metadata (Phase R1 of
[`CORE_RENAME.md`](CORE_RENAME.md)):

- The Python distribution is **`nirs4all-core`**. `nirs4all-lite` is the legacy
  distribution name; per the rename runbook it stays installable on PyPI and its
  final release becomes a thin alias that depends on `nirs4all-core` (Phase R2,
  registry action — never yank existing versions).
- The **canonical import root stays `nirs4all_lite`** so every existing import
  keeps working. Inverting canonicity (making `nirs4all_core` the implementation
  and `nirs4all_lite` the alias) is deliberately deferred: the ecosystem
  release-lock reads `bindings/python/src/nirs4all_lite/_topology.py` by path
  and must be updated in lockstep with any such move.
- The **additive `nirs4all_core` import facade** matches the distribution name.
  Its advertised public contract is deliberately core-only: inspection,
  validation, capability reporting, release topology, and facade access.
  Execution helpers from `nirs4all_lite` stay reachable through compatibility
  passthrough, but they are not part of `nirs4all_core.__all__`.
- GitHub repo (`GBeurier/nirs4all-lite` → `GBeurier/nirs4all-core`), Read the
  Docs slug, and the PyPI Trusted Publisher for `nirs4all-core` are **pending
  external admin actions** (Phase R2). Repository URLs in package metadata stay
  on the current slug until then — GitHub redirects them permanently after the
  rename.

```python
import nirs4all_core          # alias matching the distribution name (additive)
import nirs4all_lite          # canonical import — unchanged
assert nirs4all_core.upstreams is nirs4all_lite.upstreams
assert "run_portable_pipeline" not in nirs4all_core.__all__
```

## The `n4a` facade (additive brand root)

`n4a` is a short, brand-aligned Python import root (`n4a` = "nirs4all") that
re-exports the full public surface of the aggregate. It adds no behavior; it is
a facade over `nirs4all_lite`.

```python
import n4a

n4a.upstream_status()
plan = n4a.parse_execution_plan(config)
```

Both facades are **additive and non-shadowing**: they never remove or rename the
`nirs4all_lite` surface, and — per the Python strategic-path rule — they do
**not** define a top-level `nirs4all` Python module, so the full `nirs4all`
library and the aggregate continue to coexist.

The package exposes `release_topology_manifest()` as a machine-checkable summary
of this contract (schema `nirs4all-core.release-topology.v2`). It records that
the current Python distribution is `nirs4all-core`, that `nirs4all-lite` is the
superseded legacy name, and that the `nirs4all_core` import contract is not an
execution engine.

## `n4a` token disambiguation (GOV-004)

The `n4a` stem is used in three different layers of the ecosystem. They are
intentionally consistent (`n4a` = "nirs4all") but must not be conflated:

| Token | Layer | Meaning |
| --- | --- | --- |
| `n4a` | Python import | The aggregate **import facade** documented here (`import n4a`). |
| `.n4a` | File extension | The pipeline/bundle **file format** produced by the full `nirs4all` library. |
| `n4a-datasets` | Console script | The **CLI** shipped by `nirs4all-datasets`. |

A `.n4a` file is data, `n4a-datasets` is an executable, and `n4a` is an import
root. None is an alias of another.