A clear path from algebraic foundation to a stable 1.0 release.

ucon is a dimensional analysis library for engineers building systems where unit handling is infrastructure, not just convenience.

Target users:

• Library authors embedding unit handling without global state
• Domain specialists defining dimensions that match their field
• Modern stack developers wanting first-class Pydantic, Polars, MCP support

Module reorganization for v1.0 API clarity:

• ucon.basis is now a subpackage with four modules:
  • ucon.basis (__init__) — core types: Basis, BasisComponent, Vector, LossyProjection, NoTransformPath
  • ucon.basis.builtin — shipped basis instances: SI, CGS, CGS_ESU, NATURAL
  • ucon.basis.transforms — transform types and instances: BasisTransform, ConstantBoundBasisTransform, ConstantBinding, SI_TO_CGS, CGS_TO_SI, SI_TO_CGS_ESU, SI_TO_NATURAL, NATURAL_TO_SI
  • ucon.basis.graph — registry and context scoping: BasisGraph, get_default_basis(), get_basis_graph(), using_basis(), using_basis_graph()
• Integration modules moved to ucon.integrations subpackage:
  • ucon.integrations.numpy (NumberArray)
  • ucon.integrations.pandas (NumberSeries, UconSeriesAccessor)
  • ucon.integrations.polars (NumberColumn)
  • ucon.integrations.pydantic (Number type for Pydantic v2 models)
• ucon.bases and ucon.quantity removed (no backward-compat shims)
• All symbols remain importable from ucon.basis and ucon via re-exports
• Package discovery changed from explicit list to setuptools.packages.find

Previous versions include:

• ucon.basis (Basis, BasisComponent, Vector, BasisTransform, BasisGraph, ConstantBoundBasisTransform)
• ucon.dimension (Dimension as frozen dataclass backed by basis-aware Vector)
• ucon.core (Scale, Unit, UnitFactor, UnitProduct, Number, Ratio, UnitSystem, RebasedUnit, Exponent)
• ucon.maps (Map, LinearMap, AffineMap, ComposedMap, LogMap, ExpMap, ReciprocalMap)
• ucon.contexts (ConversionContext, ContextEdge, using_context, spectroscopy, boltzmann)
• ucon.graph (ConversionGraph, default graph, get_default_graph(), using_graph(), cross-basis conversion)
• ucon.units (SI + imperial + information + angle + ratio units, callable syntax, si and imperial systems, get_unit_by_name())
• ucon.integrations.numpy (NumberArray for vectorized operations on dimensioned arrays)
• ucon.integrations.pandas (NumberSeries wrapper and UconSeriesAccessor)
• ucon.integrations.polars (NumberColumn wrapper)
• ucon.integrations.pydantic (Number type for Pydantic v2 models)
• Callable unit API: meter(5), (mile / hour)(60)
• Number.simplify() for base-scale normalization
• Pseudo-dimensions: ANGLE, SOLID_ANGLE, RATIO, COUNT with semantic isolation
• Uncertainty propagation: meter(1.234, uncertainty=0.005) with quadrature arithmetic
• User-definable dimensional bases via Basis and BasisGraph
• Dimension now uses basis-aware Vector with explicit basis reference
• Pydantic v2 integration with JSON serialization
• Unit string parsing: get_unit_by_name("kg*m/s^2")
• Auto-generated dimension.pyi stubs for IDE code completion
• Basis context scoping: using_basis(), using_basis_graph(), get_default_basis()
• Quantity string parsing: parse("1.234 ± 0.005 m") → Number with uncertainty
• Physical constants: Constant class with CODATA 2022 values and uncertainty propagation
• Logarithmic units: pH with concentration dimension, dBm, dBW, dBV, dBSPL
• Natural units: NATURAL basis with c=ℏ=k_B=1, ConstantBoundBasisTransform for non-square transforms
• Namespace package support: pkgutil.extend_path enables coexistence with ucon-tools
• NumPy array support: units.meter([1, 2, 3]) → NumberArray
• Vectorized conversion, arithmetic, uncertainty propagation through arrays
• Pandas accessor: df['height'].ucon.with_unit(units.meter).to(units.foot)
• Polars column wrapper: NumberColumn(series, unit=units.meter)
• Optional dependencies: pip install ucon[numpy], ucon[pandas], ucon[polars]
• Performance caching: conversion paths, scale factors, unit multiplication

Theme: Algebraic foundation.

• Vector and Dimension classes
• Unit/Scale separation: Unit is atomic, UnitFactor pairs unit+scale
• UnitProduct with fold_scale() and _residual_scale_factor
• Exponent algebraic operations (__mul__, __truediv__, to_base)
• Scale/Exponent integration for prefix arithmetic

Outcomes:

• All units acquire explicit dimensional semantics
• Enables composable and type-safe dimensional operations
• Establishes the mathematical foundation for future conversions
• Unified algebraic foundation for all scaling and magnitude operations
• Clean Unit/Scale separation: Unit is an atomic symbol, UnitFactor pairs it with a Scale
• UnitProduct correctly tracks residual scale from cancelled units
• Type system is ready for a ConversionGraph to be built on top

Theme: First useful release.

• Map hierarchy (LinearMap, AffineMap, ComposedMap)
• Quantity class (callable unit constructor)
• ConversionGraph with edge API and BFS path finding
• Number.to() wired to graph
• Default graph with SI + Imperial + conventional units
• Unit registry with get_unit_by_name()
• Graph management (get_default_graph, set_default_graph, using_graph)
• Dimension.information with bit, byte
• Vector extended to 8 components (added B for information)
• Binary scale prefixes: kibi, mebi, gibi, tebi, pebi, exbi
• Number.simplify() for base-scale normalization
• Temperature, pressure, and base SI conversion tests
• Exponent/Scale developer guide

Outcomes:

• Unified conversion taxonomy
• Reversible, dimension-checked conversions
• Scale-aware graph that leverages the Unit/UnitFactor separation from v0.3.x
• Ergonomic API: units are callable, returning Number instances
• Information dimension support (bit, byte) with binary prefix compatibility
• Number.simplify() for expressing quantities in base scale
• Forms the basis for nonlinear and domain-specific conversion families

Theme: Complete the dimension model.

• Pseudo-dimensions: angle, solid_angle, ratio (same zero vector, distinct enum identity)
• Angle units: radian, degree, gradian, arcminute, arcsecond, turn
• Solid angle units: steradian, square_degree
• Ratio units: percent, permille, ppm, ppb, basis_point
• Cross-pseudo-dimension conversion fails (enforced isolation)
• Conversion edges for all new units

Outcomes:

• Semantic isolation prevents nonsensical conversions (radian → percent)
• Rich dimensionless unit coverage for geometry, optics, finance, chemistry
• Complete dimension model ready for metrology extensions

Theme: Metrology foundation.

• Number.uncertainty: float | None
• Propagation through arithmetic (uncorrelated, quadrature)
• Propagation through conversion via Map.derivative()
• Construction: meter(1.234, uncertainty=0.005)
• Display: 1.234 ± 0.005 meter

Outcomes:

• First-class uncertainty support for scientific and engineering workflows
• Correct propagation through both arithmetic and unit conversion
• Foundation for full metrology capabilities

Theme: Cross-system architecture.

• Vector with Fraction exponents for exact arithmetic
• UnitSystem class (named dimension-to-unit mapping)
• BasisTransform class (matrix-based dimensional basis transformation)
• RebasedUnit class (provenance-preserving cross-basis unit)
• NonInvertibleTransform exception for surjective transforms
• Prebuilt systems: units.si, units.imperial
• graph.add_edge() with basis_transform parameter
• graph.connect_systems() for bulk edge creation
• Cross-basis conversion via rebased paths
• Introspection: list_transforms(), list_rebased_units(), edges_for_transform()

Outcomes:

• BasisTransform enables conversions between incompatible dimensional structures
• Matrix operations with exact Fraction arithmetic (no floating-point drift)
• Invertibility detection with clear error messages for surjective transforms
• Named unit systems for domain-specific workflows
• Foundation for custom dimension domains

Theme: API and persistence integration.

• Native Pydantic v2 support for Number
• JSON serialization/deserialization
• Pickle support
• Unit string parsing: get_unit_by_name() with Unicode and ASCII notation

Outcomes:

• Native validation and serialization for dimensioned quantities
• Enables safe configuration in data models and APIs
• Bridges ucon's algebraic model with modern Python typing ecosystems
• Unit strings parsed in both Unicode (m/s²) and ASCII (m/s^2) notation

Theme: AI agent integration.

Note: MCP functionality moved to ucon-tools in v0.9.4. Install via pip install ucon-tools[mcp].

• MCP server exposing unit conversion tools
• convert tool with dimensional validation
• list_units, list_scales, list_dimensions discovery tools
• check_dimensions compatibility tool
• stdio transport for Claude Desktop, Claude Code, Cursor
• ucon-mcp CLI entry point

Outcomes:

• Zero-code adoption for AI tool users
• Agents can perform unit-safe arithmetic without codebase integration
• Dimensional errors become visible and correctable in conversation

Theme: Logarithmic conversions.

• LogMap class: y = scale · log_base(x) + offset
• ExpMap class: y = base^(scale · x + offset)
• Composition with existing maps via @ operator
• Derivative support for uncertainty propagation
• nines unit for SRE availability (99.999% = 5 nines)
• fraction unit (renamed from ratio_one)

Outcomes:

• Foundation for logarithmic unit conversions
• SRE teams can express availability in nines notation
• Uncertainty propagates correctly through nonlinear conversions
• Paves the way for decibels, pH in v0.9.0

Theme: Type-directed validation for domain formulas.

• Human-readable derived dimension names (derived(length^3/time) not Vector(...))
• Number[Dimension] type-safe generics via typing.Annotated
• DimensionConstraint marker class for annotation introspection
• @enforce_dimensions decorator for runtime validation at function boundaries

Outcomes:

• Dimension errors caught at function boundaries with clear messages
• Domain authors declare dimensional constraints declaratively, not imperatively
• Foundation for MCP error suggestions and schema-level constraints

Theme: AI agent self-correction.

• ConversionError response model with likely_fix and hints
• Fuzzy matching for unknown units with confidence tiers (≥0.7 for likely_fix)
• Compatible unit suggestions from graph edges
• Pseudo-dimension isolation explanation
• ucon/mcp/suggestions.py module (independently testable)
• Error handling in convert(), check_dimensions(), list_units()

Outcomes:

• MCP tools return structured errors instead of raw exceptions
• High-confidence fixes enable single-retry correction loops
• AI agents can self-correct via readable error diagnostics
• Foundation for schema-level dimension constraints

Theme: Architectural prerequisites for multi-step factor-label chains.

• SI symbol coverage audit (A for ampere, kat for katal)
• catalytic_activity dimension and katal unit added
• step: int | None field in ConversionError for chain error localization
• resolve_unit() helper to reduce try/except duplication
• build_parse_error builder for malformed composite expressions
• Priority alias invariant documented for contributors

Outcomes:

• Expressions like V/mA, mA·h, µA/cm², mkat resolve correctly
• Error responses can localize failures to specific steps in a chain
• MCP server code is DRY and ready for compute's N-factor resolution
• ParseError wrapped in structured ConversionError like other error types

Theme: Multi-step factor-label calculations for AI agents.

Prerequisite for factor-label chains with countable items (tablets, doses).

• Dimension.count pseudo-dimension (zero vector, named identity)
• each unit with aliases ea, item, ct
• Pseudo-dimension isolation (count ≠ angle ≠ ratio)
• mg/ea renders correctly with mass dimension
• MCP tests for list_units(dimension="count"), fuzzy recovery

Design decision: Single each unit instead of domain-specific atomizers (dose, tablet, capsule). Atomizers are application-layer metadata, not core units.

• compute tool for dimensionally-validated factor-label chains
• ComputeStep and ComputeResult response models
• steps array in response showing intermediate dimensional state
• Per-step error localization using ConversionError.step
• Multi-factor cancellation tests (medical dosage, stoichiometry, 6-7 factor chains)
• watt_hour unit with Wh alias for energy chain tests
• Accumulator-style unit tracking (flat factor accumulation)
• Residual scale factor propagation through graph conversions
• second*second → s² parsing fix (explicit factor accumulation)

Outcomes:

• AI agents can run factor-label chains with dimensional safety at each step
• Intermediate state visible for debugging and benchmarks (SLM vs LLM comparison)
• Agents can self-correct mid-chain rather than only at the end
• Factor-label methodology preserved: 154 lb × (1 kg / 2.205 lb) × (15 mg / kg·day) yields mg/d not kg/d
• Countable items (30 ea × 500 mg/ea = 15000 mg) work in factor-label chains

Theme: Shared infrastructure for dynamic unit extension.

• ConversionGraph._name_registry (case-insensitive) and _name_registry_cs (case-sensitive)
• graph.register_unit(unit) — Register unit for name resolution within graph
• graph.resolve_unit(name) — Lookup in graph-local registry, return None if not found
• graph.copy() — Deep copy edges, shallow copy registries
• _parsing_graph ContextVar for threading resolution through parsing
• using_graph() sets both conversion and parsing context
• _lookup_factor() checks graph-local first, falls back to global
• _build_standard_graph() calls register_unit() for all standard units

Outcomes:

• Unit name resolution becomes graph-scoped, not global
• using_graph(custom_graph) automatically scopes both conversions AND name lookups
• Foundation for UnitPackage (v0.7.4) and MCP extension tools (v0.7.5)
• No global state mutation required for custom unit definitions

Theme: Config-file-based unit extension for application developers.

• UnitDef dataclass: {name, dimension, aliases}
• EdgeDef dataclass: {src, dst, factor}
• UnitPackage frozen dataclass: {name, version, units, edges, requires}
• load_package(path) — Parse TOML file into UnitPackage
• graph.with_package(pkg) — Return new graph with package contents added
• set_default_graph(graph) — Already implemented in v0.7.3
• Example package: examples/units/aerospace.ucon.toml

Outcomes:

• Implementers define domain units in TOML config files
• Units loaded at application startup without modifying library code
• Immutable composition: graph.with_package(a).with_package(b)
• No global state mutation — graphs are composed, not mutated
• Foundation for ucon.dev marketplace of domain packages

Theme: Runtime unit extension for AI agents.

• _session_graph ContextVar for session-scoped custom graphs
• define_unit(name, dimension, aliases) — Register unit in session graph
• define_conversion(src, dst, factor) — Add edge to session graph
• reset_session() — Clear session graph, return to default

• convert(..., custom_units=[...], custom_edges=[...]) — Self-contained conversion
• compute(..., custom_units=[...], custom_edges=[...]) — Self-contained multi-step
• Graph caching by definition hash for performance

Outcomes:

• Agents can bring their own units without prior registration
• Session tools minimize token cost for repeated definitions
• Inline parameters enable recovery when session state is lost
• Hybrid approach: session for efficiency, inline for fault tolerance
• Exotic domain evals (aerospace, radiation, chemeng) work without core bloat

Theme: Public documentation site.

• MkDocs Material site at docs.ucon.dev
• Getting Started, Guides, Reference, Architecture sections
• MCP Server documentation reorganized into dedicated directory
• Domain walkthroughs (nursing dosage)

Outcomes:

• Comprehensive public documentation for library users
• Clear separation of guides, reference, and architecture content
• Foundation for community adoption

Theme: Pre-call validation for AI agents.

• ucon/mcp/schema.py — extract_dimension_constraints() introspects @enforce_dimensions functions
• ucon/mcp/formulas.py — @register_formula decorator with FormulaInfo dataclass
• list_formulas MCP tool — Returns registered formulas with parameter dimensions
• call_formula MCP tool — Invokes formulas with dimensionally-validated inputs
• FormulaResult and FormulaError response models
• Error types: unknown_formula, missing_parameter, invalid_parameter, dimension_mismatch

Outcomes:

• MCP schemas declare expected dimensions per parameter
• Agents can discover formulas via list_formulas() before calling
• call_formula() validates dimensions at call time with structured errors
• Completes the type-directed correction loop
• Foundation for ucon.dev marketplace of domain formula packages

Theme: User-definable dimensional coordinate systems.

Design document: docs/internal/IMPLEMENTATION_PLAN_basis-abstraction.md

• BasisComponent class: atomic generator of a dimensional basis
• Basis class: ordered collection of components with name/symbol indexing
• Vector class: basis-aware exponent vector with named field access (v["L"], v["mana"])
• BasisTransform class: matrix-based transformation with exact Fraction arithmetic
• inverse() method: Gaussian elimination for square transforms
• embedding() method: canonical embedding for non-square projections
• LossyProjection exception: fail-by-default when projecting to zero

Outcomes:

• Dimensional basis becomes user-definable, not hardcoded to SI
• Foundation for CGS, CGS-ESU, natural units (c=ℏ=1), and custom domains
• Exact matrix arithmetic prevents round-trip drift
• New types introduced alongside existing (no breaking changes)

Theme: Graph-based transform composition and standard bases.

• BasisGraph class: graph of basis transforms with path-finding
• Transitive composition: SI→CGS + CGS→CGS-ESU = SI→CGS-ESU
• NoTransformPath exception for disconnected bases
• get_transform(source, target) with BFS and caching
• reachable_from() and are_connected() introspection
• with_transform() copy-on-extend pattern
• Standard bases: SI, CGS, CGS_ESU in ucon.bases
• Standard transforms: SI_TO_CGS, SI_TO_CGS_ESU, CGS_TO_SI

Outcomes:

• Register N-1 edges for N bases instead of N² explicit transforms
• Custom domains (game, finance) correctly isolated from SI
• Separation of concerns: BasisGraph (type checking) vs ConversionGraph (numeric conversion)

Theme: Wire new Vector into Dimension.

• Dimension.vector uses new basis-aware Vector
• Dimension.basis property delegating to vector.basis
• Dimension.from_components(basis, length=1, mass=2) factory
• Backward-compatible construction for SI dimensions
• Dimension refactored from Enum to frozen dataclass
• resolve(vector) function for dimension lookup/creation
• Pseudo-dimensions via Dimension.pseudo() factory with tag isolation
• Delete ucon/algebra.py (pulled forward from v0.9.0)
• Move Exponent to ucon/core.py (pulled forward from v0.9.0)

Outcomes:

• Dimensions carry explicit basis reference
• Foundation for cross-basis dimensional comparison
• Clean module structure achieved early

Theme: Cross-basis conversion validation and BasisTransform unification.

• Auto-generated dimension.pyi stubs for IDE code completion (make stubs)

• ConversionGraph accepts BasisGraph as constructor parameter
• add_edge() validates cross-basis edges via BasisGraph
• convert() validates dimensional compatibility via BasisGraph
• Unit.basis property: return self.dimension.vector.basis
• Unit.is_compatible(other) using BasisGraph

• Update RebasedUnit to use ucon.basis.BasisTransform
• Update ConversionGraph cross-basis methods to use new BasisTransform
• Delete old BasisTransform from ucon/core.py
• Remove NewBasisTransform alias from ucon/__init__.py
• Export only BasisTransform from ucon.basis

Outcomes:

• IDE code completion works for Dimension.length, Dimension.velocity, etc.
• Cross-basis unit edges validated at registration time
• Dimensional errors caught before numeric conversion attempted
• Single unified BasisTransform implementation

Theme: Thread-safe basis isolation.

• _default_basis ContextVar with SI fallback
• _basis_graph_context ContextVar for graph scoping
• using_basis(basis) context manager
• using_basis_graph(graph) context manager
• get_default_basis() accessor
• get_basis_graph() accessor
• set_default_basis_graph() / reset_default_basis_graph() for module-level control
• Dimension.from_components() and Dimension.pseudo() respect context basis

Outcomes:

• Per-thread/task basis isolation (same pattern as using_graph())
• Injectable basis graphs for testing and multi-tenant scenarios
• Dynamic cross-system conversion paths via context scoping

Theme: Ergonomic input.

• parse("60 mi/h") → Number (quantity + unit parsing)
• parse("kg * m / s^2") → UnitProduct (completed in v0.6.0 via get_unit_by_name())
• Alias resolution (meters, metre, m all work) (completed in v0.6.0)
• Uncertainty parsing: parse("1.234 ± 0.005 m") with ± and +/- notation
• Parenthetical uncertainty: parse("1.234(5) m") (metrology convention)
• Scientific notation: parse("1.5e3 m")
• Dimensionless numbers: parse("100") returns Number with no unit
• Example: examples/parsing/parse_quantities.py

Outcomes:

• Human-friendly unit input for interactive and configuration use cases
• Robust alias handling for international and domain-specific conventions
• Complete round-trip: parse → compute → serialize
• Uncertainty input matches common scientific notation conventions

Theme: CODATA physical constants with uncertainty propagation.

• Constant dataclass with symbol, name, value, unit, uncertainty, source
• SI defining constants (exact): c, h, e, k_B, N_A, K_cd, ΔνCs
• Derived constants (exact): ℏ, R, σ
• Measured constants: G, α, m_e, m_p, m_n, ε₀, μ₀
• Unicode and ASCII aliases
• Arithmetic operators return Number with uncertainty propagation
• constants module exported from ucon

Outcomes:

• Physical constants with CODATA 2022 uncertainties
• E=mc², E=hν formulas work naturally
• Measured constant uncertainty propagates through calculations

Theme: Decibels, nepers, and pH scale.

• LogMap/ExpMap for logarithmic conversions (completed in v0.6.x)
• decibel, bel, neper units (completed in v0.9.0)
• Reference-level infrastructure for dBm, dBV, dBW, dBSPL variants (completed in v0.9.0)
• pH unit with concentration ↔ pH conversion
• Uncertainty propagation through logarithmic conversions (via LogMap.derivative())

Outcomes:

• Acoustics (dB), chemistry (pH), and signal processing domains enabled
• Reference-level variants (dBm = dB relative to 1 mW) supported
• pH conversion uses concentration dimension for dimensional consistency

Theme: AI agent access to physical constants.

• list_constants(category) MCP tool
• define_constant(symbol, value, unit, uncertainty) MCP tool
• Session constants infrastructure (_session_constants ContextVar)
• all_constants() function to enumerate built-in constants
• get_constant_by_symbol() function for constant lookup
• Constant.category field for filtering

Outcomes:

• AI agents can discover and use physical constants
• Custom constants for domain-specific calculations
• Session constants persist until reset_session() is called

Theme: Custom dimensional bases where c=ℏ=1, plus MCP reliability fixes.

• ConstantBoundBasisTransform with inverse() for non-square transforms
• ConstantBinding dataclass for tracking which constants absorb dimensions
• NATURAL basis with single energy dimension
• SI → NATURAL transform: T→E⁻¹, L→E⁻¹, M→E, Θ→E (via ℏ, c, k_B)
• NATURAL → SI inverse transform
• Documentation and examples (examples/basis/)

• All session-dependent tools use FastMCP Context injection

Outcomes:

• Natural units leverage custom basis infrastructure
• Foundation for particle physics and quantum field theory domains
• MCP tools are more reliable for multi-call agent workflows

Theme: Separate MCP tooling into ucon-tools package.

• Extract ucon.mcp subpackage to ucon-tools repository
• Add pkgutil.extend_path() for namespace package coexistence
• Remove MCP optional dependency and entry point from pyproject.toml
• Update documentation to reference ucon-tools[mcp] for MCP features
• MCP docs moved to ucon-tools (sourced via git submodule)

Outcomes:

• Core ucon package has no MCP dependencies (simpler install, broader compatibility)
• MCP tooling available via pip install ucon-tools[mcp]
• Namespace package allows both packages to coexist under ucon.*
• ucon-tools can iterate independently on AI agent features

Theme: NumPy and DataFrame integration.

• NumberArray class with vectorized arithmetic and conversion
• Scalar and per-element uncertainty propagation
• Reduction operations: sum(), mean(), std(), min(), max()
• Comparison operators returning boolean arrays
• Callable syntax: meter([1, 2, 3]) → NumberArray
• Map array support (LinearMap, AffineMap, LogMap, ExpMap)
• Pandas integration: NumberSeries and UconSeriesAccessor
• Polars integration: NumberColumn
• Optional dependencies: ucon[numpy], ucon[pandas], ucon[polars]
• Performance caching (conversion paths, scale factors, unit products)
• Benchmarks: make benchmark, make benchmark-pint

Outcomes:

• Seamless integration with NumPy-based scientific workflows
• Efficient batch conversions for large datasets (100M+ elements/sec)
• First-class support for data science workflows with Pandas and Polars
• Unit-safe transformations on tabular data
• Performance competitive with pint, much faster on creation
• Lazy caching approximates fixed registry without startup cost

Theme: Structural clarity for v1.0 API surface.

• ucon/basis.py split into ucon/basis/ subpackage (__init__, builtin, transforms, graph)
• ucon/bases.py removed (contents split into ucon.basis.builtin and ucon.basis.transforms)
• Integration modules moved to ucon/integrations/ (numpy, pandas, polars, pydantic)
• ucon/quantity.py removed (backward-compat shim; Number, Ratio importable from ucon.core or ucon)
• All public symbols remain importable from ucon.basis and ucon via re-exports
• Package discovery changed to setuptools.packages.find for automatic subpackage inclusion

Outcomes:

• Clear separation of concerns within the basis subsystem (types, instances, transforms, registry)
• Integration modules grouped under a single namespace
• Acyclic import dependency order within ucon.basis subpackage
• Clean break — no backward-compat shims for removed modules
• Module layout stable for v1.0 API freeze

Theme: Production ready.

• ReciprocalMap(a) — inversely proportional map: y = a / x
• Self-inverse property: inverse() returns ReciprocalMap(a)
• NumPy array support
• Derivative for uncertainty propagation: f'(x) = -a / x²

• EXPOSURE dimension: I·T/M = (1, 0, -1, 1, 0, 0, 0, 0)
• coulomb_per_kilogram bridge unit (named SI bridge for exposure)
• roentgen unit with R_exp alias
• Conversion: 1 R = 2.58e-4 C/kg

• SI_TO_CGS_EMU basis transform (SI current → L^(1/2)·M^(1/2)·T^(-1) in CGS)
• 6 CGS-EMU dimensions: current, charge, voltage, resistance, capacitance, inductance
• 7 CGS-EMU units: biot (abampere), abcoulomb, abvolt, abohm, abfarad, abhenry, gilbert
• Cross-basis edges: ampere↔biot (0.1), coulomb↔abcoulomb (0.1), volt↔abvolt (1e8), ohm↔abohm (1e9), farad↔abfarad (1e-9), henry↔abhenry (1e9)
• _rebased changed from dict[Unit, RebasedUnit] to dict[Unit, list[RebasedUnit]] to support multiple basis transforms per source unit

• ucon/contexts.py — new module for cross-dimensional conversion contexts
• ContextEdge(src, dst, map) frozen dataclass
• ConversionContext(name, edges, description) frozen dataclass
• using_context(*contexts) context manager (copies graph, injects edges, scopes via using_graph())
• Cross-dimensional BFS fallback in _convert_units() (searches all dimension partitions)
• Built-in spectroscopy context: meter↔hertz via ReciprocalMap(c), hertz→joule via LinearMap(h), meter→joule via ReciprocalMap(hc), joule→reciprocal_meter via LinearMap(1/hc)
• Built-in boltzmann context: kelvin→joule via LinearMap(k_B)

• Réaumur temperature (reaumur, °Ré, degRe) — 1 °Ré = 1.25 °C
• Historical electrical: international_ampere (A_int), international_volt (V_int), international_ohm (ohm_int)

• API audit — every public symbol classified as stable/internal/rename
• Domain walkthroughs — 5 guides (nursing, chem-e, aerospace, finance, EE)
• API reference generation — 15 module pages via mkdocstrings
• Performance benchmarks documented
• Security review complete
• LTS policy stated

• API freeze with semantic versioning commitment
• 2+ year LTS commitment

Outcomes:

• Stable, well-tested release
• Fully type-safe and validated core
• Production-ready for integration into scientific and engineering workflows
• Near-parity with Pint on raw unit count (~215 unique units across 67+ dimensions)
• CGS-EMU system complements existing CGS and CGS-ESU for complete classical electromagnetic coverage
• Cross-dimensional contexts enable spectroscopy and thermodynamic conversions without polluting the global graph

Theme: Enriched .ucon.toml format toward full ConversionGraph serialization.

• [package] table for structured metadata (name, version, description, requires)
• shorthand field on UnitDef for explicit display symbols
• requires field with dependency validation on with_package()
• [[constants]] section for domain-specific physical constants
• Explicit map type on [[edges]] (linear, affine, log, exp, reciprocal)
• ExpMap in package format map type registry
• Product edges verified: composite src/dst expressions resolve correctly

Outcomes:

• Domain packages can define constants alongside units and edges
• Non-linear conversion maps (logarithmic, reciprocal) expressible in TOML
• Package dependency ordering enforced at load time
• Foundation for full ConversionGraph serialization in v1.2.0

"If it can be measured, it can be represented. If it can be represented, it can be validated. If it can be validated, it can be trusted."