# Contributing to the SAME Analog Modular Ecosystem Specification

Thank you for your interest in contributing to the **SAME Analog Modular
Ecosystem**.

Because SAME is a metrology-grade computing specification targeting
$10\text{ ppm}$ precision and $90\text{ dB}$ SNR, we maintain strict
engineering, mathematical, and procedural standards for all contributions. This
guide outlines how to set up your environment, write compliant Typst markup,
enforce our executable math paradigm, and submit pull requests.

## 1. The Executable Specification Paradigm

The defining principle of this repository is that **the specification is its own
test suite**.

We do not manually transcribe calculated values into prose. Every mathematical
claim, noise derivation, tolerance budget, and physical scaling law presented in
the text must be directly accompanied by a compile-time assertion using our
custom metrology library (`lib/assert-aeq.typ` and `lib/apply-prefix.typ`).

### The Rule of Zero-Copy Math

When adding or modifying any numerical derivation:

1. **Calculate programmatically:** Define variables using Typst math expressions
  and SI helpers.
2. **Assert sanity at compile time:** Pass the calculated variable and the
  expected target through `#assert-aeq`.
3. **Typeset the output:** Render the expression using standard Typst math
  markup.

#### Example

```typst
#let v_noise_excess = (
  5 * calc.pow(10, -15 / 20) * calc.sqrt(20000) * calc.pow(10, -6)
)
// 1. Compile-time assertion using named SI prefixes
#assert-aeq(v_noise_excess, apply-prefix(125.74, "micro"))

// 2. Visual presentation block
$
  V_("noise","excess") & approx qty(5, "V") times 10^(-15/20) times sqrt(20000) dot 10^-6 \
  V_("noise","excess") & approx qty(5, "V") times 0.1778 times num("141.4e-6") approx qty(125.74, "uV")
$
```

If you modify a foundational parameter (e.g. system bandwidth or reference
voltages), Typst must re-evaluate all downstream derivations. **If any assertion
fails, the PDF build will halt.**

## 2. Development Setup

### Prerequisites

- **Typst CLI**: Version `0.15.1` or higher.
- **Git:** For version control.

### Building and Testing

1. **Clone the repository:**

  ```bash
    git clone git@denischevalier.fr:/srv/git/same.git
    cd same
  ```

1. **Enable git hooks:** To automatically inject required SPDX license headers
  on newly created `.typ` files:

  ```bash
    chmod +x .githooks/pre-commit
    git config core.hooksPath .githooks
  ```

1. **Run a live watch build:**

   ```bash
     typst watch preamble.typ specification.pdf
   ```

   *If your edits break an assertion metrology check anywhere in the 90+ pages,
   Typst will throw an immediate compiler error in your terminal.*
2. **Perform a clean release compile:**

  ```bash
    typst compile preamble.typ specification.pdf
  ```

## 3. Structural & Content Guidelines

### Enumerating Physical Error Sources (Section 4.3)

When adding a new error mechanism or circuit non-ideality to Section 4.3, you
**must** follow the standard 6-part structure:

1. **Physical mechanism:** What physical/thermodynamic law causes this error?
2. **Mathematical model:** First-principles equations governing the behavior.
3. **Typical magnitude:** Numerical evaluation using commodity through-hole
  component specs.
4. **Where it enters:** Circuit nodes, PCB traces, or mechanical interfaces
  vulnerable to this mechanism.
5. **Scaling law:** How the error scales with frequency, temperature, resistance,
  bandwidth, or geometry.
6. **Compensation strategy:** Cross-reference to the topological mitigation or
  physical layout rules.

### Vector Graphics & Visual Standards

- **No Binary Raster Graphics:** Do not commit `.png`, `.jpg`, or bitmap
  images for technical drawings, schematics, or plots.
- **CeTZ & CeTZ-Plot:** All mechanical dimensions, panel grids, and mathematical
  curves must be written natively using `CeTZ` or `CeTZ-plot` inside `/diagrams`
  or `/charts`.
- **Circuits with Zap:** Circuits schematics must be written using `zap` code
  directly within the Typst source tree, under `/schematics`.
- **Typographic Consistency:** All text inside vector graphics must use the
  document's native typography and unit formatting library (`lib/unify.typ`).

## 4. Licensing & SPDX Headers

This project is tri-licensed to properly cover prose, hardware CAD, and
executable code. **Every new file commited to the repository must include the
appropriate SPDX header at line 1:

```typst
// / SPDX-FileCopyrightText: 2026 Denis Chevalier \<perso\@denischevalier.fr>
// / SPDX-License-Identifier: CC-BY-SA-4.0
// / SPDX-License-Identifier: CERN-OHL-S-2.0+
// / SPDX-License-Identifier: GPL-3.0-or-later
// 
// The prose, explanatory text, rendered figures, tables, and mathematical
// content of this specification are licensed under CC BY-SA 4.0. If a later
// version of CC BY-SA is published, the author grants permission to distribute
// this work under that later version as well.
// 
// Hardware designs contained herein (schematics, PCB layouts, mechanical
// drawings, and CAD models) are licensed under CERN-OHL-S-2.0+.
// 
// All executable code, helper libraries (`lib/*`), metrology assertions, and
// embedded verification scripts throughout the source documents are licensed
// under the GNU General Public License v3.0 or later (GPL-3.0-or-later).
```

## 5. Submitting Pull Requests

To keep the history clean and maintainable:

1. **Atomic Commits:** Make small, focused commits. Separate structural Typst
  refactoring from mathematical derivations and text revisions.
2. **Verify Local Builds:** Ensure `typst compile preamble.typ` completes with
  zero errors and zero warnings before opening a PR.
3. **PR Description Checklist:**
    - Explain the engineering rationale behind any parameter changes.
    - Cite relevant metrology literature, datasheets, or academic papers if
        introducing new concepts.
    - Confirm all assertions pass.
4. **Clean Diffs:** Avoid re-formating unrelated `.typ` files. Keep line breaks
  logical (semantic line breaks are preferred).

## Questions or Discussion?

If you are planning a major structural change to the specification, please send
a mail to [Denis Chevalier](perso@denischevalier.fr) to discuss the
architectural implications before writing code.