Waltham-Data-Science · audriB · Jun 10, 2026 · Jun 10, 2026 · Jun 10, 2026 · Jun 10, 2026
diff --git a/.cursorrules b/.cursorrules
@@ -1,7 +1,7 @@
 # NDI Cursor Rules
 
 ## 1. Project Context
-This is the NDI (Neuroscience ndi_gui_Data Interface) Python port. It is a "Lead-Follow" project where the MATLAB codebase is the Source of Truth.
+This is the NDI (Neuroscience Data Interface) Python port. It is a "Lead-Follow" project where the MATLAB codebase is the Source of Truth.
 
 ## 2. Core Instructions
 Before proposing or writing any code, you MUST read and adhere to the following project-specific files:

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -10,12 +10,13 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
 
       - name: Set up Python 3.12
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5
         with:
           python-version: "3.12"
+          cache: pip
 
       - name: Install linting tools
         run: |
@@ -33,15 +34,16 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.10", "3.11", "3.12"]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5
         with:
           python-version: ${{ matrix.python-version }}
+          cache: pip
 
       - name: Install with ndi_install.py
         run: |
@@ -51,21 +53,16 @@ jobs:
       - name: Validate installation
         run: python -m ndi check
 
+      # NOTE: cloud credentials are intentionally NOT injected here. Tests that
+      # need a live cloud account (and the destructive MATLAB BYOL tests gated
+      # by NDI_CLOUD_TEST_USER_HAS_MATLAB_LICENSE) skip themselves when the
+      # variables are unset, and run only in the scheduled test-cloud-api.yml
+      # workflow. This keeps secrets off every collaborator's per-PR run.
       - name: Run tests with coverage
-        env:
-          NDI_CLOUD_USERNAME: ${{ secrets.TEST_USER_2_USERNAME }}
-          NDI_CLOUD_PASSWORD: ${{ secrets.TEST_USER_2_PASSWORD }}
-          # The CI test account does not have a registered MATLAB
-          # license, so the destructive BYOL tests (DELETE
-          # /users/me/matlab-license) are allowed to run; they will
-          # clean up after themselves. The license guard in
-          # tests/_matlab_license_guard.py enforces this at module-import
-          # time and refuses to run if this variable is unset.
-          NDI_CLOUD_TEST_USER_HAS_MATLAB_LICENSE: "false"
         run: |
           # Use sys.monitoring (PEP 669) on Python 3.12+ for faster coverage.
           # CTracer (sys.settrace) is catastrophically slow on 3.12 when
           # importing large packages like openminds (~6 min vs ~2 sec).
           COVERAGE_CORE=$(python -c "import sys; print('sysmon' if sys.version_info >= (3,12) else 'ctrace')")
           export COVERAGE_CORE
-          pytest tests/ -v --tb=short --cov=src/ndi --cov-report=term-missing
+          pytest tests/ -n auto -v --tb=short --cov=src/ndi --cov-report=term-missing
diff --git a/.github/workflows/test-cloud-api.yml b/.github/workflows/test-cloud-api.yml
@@ -23,12 +23,13 @@ jobs:
         environment: [prod, dev]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
 
       - name: Set up Python 3.12
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5
         with:
           python-version: "3.12"
+          cache: pip
 
       - name: Install with ndi_install.py
         run: |
@@ -40,5 +41,10 @@ jobs:
           NDI_CLOUD_USERNAME: ${{ matrix.user == 1 && secrets.TEST_USER_1_USERNAME || secrets.TEST_USER_2_USERNAME }}
           NDI_CLOUD_PASSWORD: ${{ matrix.user == 1 && secrets.TEST_USER_1_PASSWORD || secrets.TEST_USER_2_PASSWORD }}
           CLOUD_API_ENVIRONMENT: ${{ matrix.environment }}
+          # The destructive MATLAB BYOL lifecycle tests run here (the scheduled,
+          # non-PR workflow) rather than per-PR CI. "false" => the test account
+          # has no registered license, so they run end-to-end and clean up.
+          NDI_CLOUD_TEST_USER_HAS_MATLAB_LICENSE: "false"
         run: |
-          pytest tests/test_cloud_live.py -v --tb=short
+          pytest tests/test_cloud_live.py tests/test_cloud_matlab_license.py \
+            tests/test_cloud_hello_matlab.py -v --tb=short
diff --git a/.github/workflows/test-symmetry.yml b/.github/workflows/test-symmetry.yml
@@ -19,12 +19,12 @@ jobs:
     steps:
       # ── Checkout both repos ────────────────────────────────────────────
       - name: Check out NDI-python
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
         with:
           path: NDI-python
 
       - name: Check out NDI-matlab (matching branch, fall back to main)
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
         with:
           repository: VH-Lab/NDI-matlab
           # Use the same branch name as NDI-python so paired feature
@@ -37,7 +37,7 @@ jobs:
 
       - name: Check out NDI-matlab (main fallback)
         if: steps.matlab_checkout_branch.outcome == 'failure'
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
         with:
           repository: VH-Lab/NDI-matlab
           ref: main
@@ -51,7 +51,7 @@ jobs:
           echo "DISPLAY=:99" >> $GITHUB_ENV
 
       - name: Set up MATLAB
-        uses: matlab-actions/setup-matlab@v2
+        uses: matlab-actions/setup-matlab@aa8bbc7b76daa63c5d456d1430cbd6cb5b626ab4  # v2
         with:
           release: latest
           cache: true
@@ -61,10 +61,10 @@ jobs:
             Signal_Processing_Toolbox
 
       - name: Install MatBox
-        uses: ehennestad/matbox-actions/install-matbox@v1
+        uses: ehennestad/matbox-actions/install-matbox@8fe220fbaec9e119ec5081eb917c8e016e275f1e  # v1
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5
         with:
           python-version: "3.12"
 
@@ -85,7 +85,7 @@ jobs:
       # +ndi/+symmetry folder (which has its own narrow requirements.txt),
       # and TestSuite.fromFolder discovers tests in that directory tree.
       - name: "Stage 1: MATLAB makeArtifacts"
-        uses: matlab-actions/run-command@v2
+        uses: matlab-actions/run-command@37b454c384483087929a3d652be474ba585a9659  # v2
         with:
           command: |
             cd("NDI-matlab");
@@ -124,7 +124,7 @@ jobs:
 
       # ── Stage 3: MATLAB readArtifacts ──────────────────────────────────
       - name: "Stage 3: MATLAB readArtifacts (reads Python artifacts)"
-        uses: matlab-actions/run-command@v2
+        uses: matlab-actions/run-command@37b454c384483087929a3d652be474ba585a9659  # v2
         with:
           command: |
             cd("NDI-matlab");

diff --git a/.gitignore b/.gitignore
@@ -12,6 +12,8 @@ wheels/
 *.egg-info/
 *.egg
 .eggs/
+# Build artifacts are regenerated by CI; never commit them.
+*.tar.gz
 
 # Virtual environments
 .venv/

diff --git a/AGENTS.md b/AGENTS.md
@@ -2,7 +2,7 @@
 
 ## 1. Role & Mission
 
-You are an AI Developer for the NDI (Neuroscience ndi_gui_Data Interface) project. Your mission is to maintain 1:1 functional and semantic parity between the mature MATLAB (Source of Truth) codebase and the Python port.
+You are an AI Developer for the NDI (Neuroscience Data Interface) project. Your mission is to maintain 1:1 functional and semantic parity between the mature MATLAB (Source of Truth) codebase and the Python port.
 
 ## 2. The Mandatory Knowledge Base
 
@@ -85,5 +85,5 @@ black src/ tests/ && ruff check src/ tests/ && pytest tests/ -x -q
 
 ## 6. Directory Mapping Reference
 
-- **MATLAB Source:** `VH-ndi_gui_Lab/NDI-matlab` (GitHub)
+- **MATLAB Source:** `VH-Lab/NDI-matlab` (GitHub)
 - **Python Target:** `src/ndi/[namespace]/` (Mirrors MATLAB `+namespace/`)
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -1,7 +1,6 @@
 include LICENSE
 include README.md
 include CHANGELOG.md
-include MATLAB_MAPPING.md
 
 recursive-include src/ndi/ndi_common *.json *.txt *.tsv *.tsv.gz *.obo *.md
 recursive-include src/ndi/ndi_common/example_binaries *

diff --git a/REPO_AUDIT.md b/REPO_AUDIT.md
@@ -1,5 +1,13 @@
 # NDI Cloud: MATLAB vs Python Structure Audit
 
+> [!NOTE]
+> **SUPERSEDED.** This is a narrow, cloud-module-only structural audit. It has
+> been superseded by the ecosystem-wide parity & audit report
+> (`ECOSYSTEM_AUDIT_2026-06.md`), which covers the full NDI-python codebase
+> (time system, epoch/DAQ, documents, ontology, security, packaging) and the
+> rest of the NDI ecosystem. Retained for historical context; consult the
+> ecosystem report for the current source of truth.
+
 This document analyzes every structural difference between the MATLAB and Python
 implementations of the NDI Cloud module, explains why each difference exists,
 and recommends whether to change or keep it.

diff --git a/docs/developer_notes/PYTHON_PORTING_GUIDE.md b/docs/developer_notes/PYTHON_PORTING_GUIDE.md
@@ -24,13 +24,23 @@ To port or update a function, agents must follow these steps:
 2. **Sync the Interface:** If the function is missing or outdated, update the YAML entry first based on the MATLAB `.m` file.
 3. **Record the Sync Hash:** Store the short git hash of the MATLAB `.m` file being ported in the `matlab_last_sync_hash` field. Obtain it with: `git log -1 --format="%h" -- <path-to-matlab-file>`. This allows future comparison to detect upstream MATLAB changes.
 4. **Implement:** Write the Python code to satisfy the `input_arguments` and `output_arguments` defined in the YAML.
-5. **Log & Notify:** Record the sync date in the YAML's `decision_log` (e.g., `"Synchronized with MATLAB main as of 2026-03-12."`). ndi_document any intentional divergences. Explicitly tell the user what changes were made to the bridge file so they can review the contract.
-
-## 4. Input Validation: Pydantic is Mandatory
-
-To replicate the robustness of the MATLAB `arguments` block, use Pydantic for all public-facing API functions.
-
-- **Decorator:** Use the `@pydantic.validate_call` decorator on all functions.
+5. **Log & Notify:** Record the sync date in the YAML's `decision_log` (e.g., `"Synchronized with MATLAB main as of 2026-03-12."`). Document any intentional divergences. Explicitly tell the user what changes were made to the bridge file so they can review the contract.
+
+## 4. Input Validation: Pydantic at Trust Boundaries
+
+To replicate the robustness of the MATLAB `arguments` block, use Pydantic
+validation where untrusted input crosses into the library.
+
+- **Where to apply:** Decorate public entry points at **trust boundaries** —
+  functions that receive user-supplied, file-derived, or cloud-derived input
+  (the cloud layer, document/query construction from external JSON, CLI/API
+  surfaces). Do **not** blanket-apply `@pydantic.validate_call` to every
+  internal method: the hot core paths (document/query/session/element/daq/
+  syncgraph/navigator) call each other with already-validated, often
+  numpy-heavy arguments, where per-call validation adds overhead and friction
+  for no safety gain. Validate once at the edge, then trust internally.
+- **Decorator:** Use the `@pydantic.validate_call` decorator on the
+  boundary-facing functions identified above.
 - **Type Mirroring:**
   - MATLAB `double`/`numeric` → Python `float | int`
   - MATLAB `char`/`string` → Python `str`
@@ -47,8 +57,11 @@ MATLAB allows multiple return values natively. In Python, these must be returned
 
 All Python code must pass formatting and linting before being committed.
 
-- **Black:** The sole code formatter. Use default line length (88).
-- **Ruff:** The primary linter. Run `ruff check --fix` before committing.
+- **Black:** The sole code formatter. Line length is **100** (matching
+  `pyproject.toml`'s `[tool.black] line-length` and `AGENTS.md`). Run
+  `black src/ tests/` before committing.
+- **Ruff:** The primary linter, also configured at line length 100. Run
+  `ruff check --fix` before committing.
 
 ## 7. Error Handling & Documentation
 

diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -5,12 +5,12 @@
 ### Prerequisites
 
 - Python 3.10 or later
-- Git (for installing VH-ndi_gui_Lab dependencies)
+- Git (for installing VH-Lab dependencies)
 
 ### Install from source
 
 ```bash
-git clone https://github.com/Waltham-ndi_gui_Data-Science/NDI-python.git
+git clone https://github.com/Waltham-Data-Science/NDI-python.git
 cd NDI-python
 python -m venv venv
 source venv/bin/activate  # Linux/macOS (venv\Scripts\activate on Windows)

diff --git a/docs/index.md b/docs/index.md
@@ -1,14 +1,14 @@
 # NDI-Python
 
-**Neuroscience ndi_gui_Data Interface** - Python implementation.
+**Neuroscience Data Interface** - Python implementation.
 
 NDI provides a unified framework for managing, querying, and analyzing neuroscience experimental data across different acquisition systems.
 
 ## Overview
 
-NDI-Python is a complete port of the [MATLAB NDI](https://github.com/VH-ndi_gui_Lab/NDI-matlab) codebase, providing:
+NDI-Python is a complete port of the [MATLAB NDI](https://github.com/VH-Lab/NDI-matlab) codebase, providing:
 
-- **ndi_document-based metadata** with JSON schema validation
+- **Document-based metadata** with JSON schema validation
 - **SQLite database** backend for persistent storage and rich queries
 - **Time synchronization** across heterogeneous recording devices
 - **DAQ readers** for Intan, Blackrock, CED Spike2, and SpikeGadgets
@@ -33,12 +33,12 @@ with ndi_session_mock('demo') as session:
 ## Installation
 
 ```bash
-git clone https://github.com/Waltham-ndi_gui_Data-Science/NDI-python.git
+git clone https://github.com/Waltham-Data-Science/NDI-python.git
 cd NDI-python
 ```
 
-See the [Getting Started guide](getting-started.md) or the [README](https://github.com/Waltham-ndi_gui_Data-Science/NDI-python#readme) for full installation instructions including VH-ndi_gui_Lab dependency setup.
+See the [Getting Started guide](getting-started.md) or the [README](https://github.com/Waltham-Data-Science/NDI-python#readme) for full installation instructions including VH-Lab dependency setup.
 
 ## MATLAB Migration
 
-If you're migrating from MATLAB NDI, see [MATLAB_MAPPING.md](https://github.com/Waltham-ndi_gui_Data-Science/NDI-python/blob/main/MATLAB_MAPPING.md) for a complete function-by-function reference.
+If you're migrating from MATLAB NDI, see [MATLAB_MAPPING.md](https://github.com/Waltham-Data-Science/NDI-python/blob/main/MATLAB_MAPPING.md) for a complete function-by-function reference.
diff --git a/docs/matlab-migration.md b/docs/matlab-migration.md
@@ -2,11 +2,11 @@
 
 This page summarizes key differences when migrating from MATLAB NDI to Python NDI.
 
-For the complete function-by-function mapping, see [MATLAB_MAPPING.md](https://github.com/Waltham-ndi_gui_Data-Science/NDI-python/blob/main/MATLAB_MAPPING.md).
+For the complete function-by-function mapping, see [MATLAB_MAPPING.md](https://github.com/Waltham-Data-Science/NDI-python/blob/main/MATLAB_MAPPING.md).
 
 ## Key API Differences
 
-### ndi_query Syntax
+### Query Syntax
 
 **MATLAB:**
 ```matlab