refactor: clarify fleet configuration boundaries #181

Merged

nimmo merged 2 commits from refactor/fleet-boundary-cleanup into main 2026-08-17 00:35:09 +01:00

Conversation 3 Commits 2 Files changed 14 +3651 -3437

nimmo commented 2026-08-17 00:05:45 +01:00

Owner

Copy link

Summary

• replace duplicated Vega/Lyra Paseo daemon configuration with a reusable fleet service module
• keep scripts/nixos-update-remediation.py as the stable executable while splitting implementation into core, model, validation, publication, and CLI modules
• extend workflow path coverage and safety assertions for the internal package
• refresh the README for all six active hosts and the new subsystem boundaries

Validation

• ruff check scripts/nixos-update-remediation.py scripts/nixos_update_remediation
• ./tests/nixos-update-remediation-regressions.sh
• evaluated Vega and Lyra Paseo hostnames through their NixOS configurations
• nix flake check

Refs #178
Refs #179
Refs #180

## Summary - replace duplicated Vega/Lyra Paseo daemon configuration with a reusable fleet service module - keep `scripts/nixos-update-remediation.py` as the stable executable while splitting implementation into core, model, validation, publication, and CLI modules - extend workflow path coverage and safety assertions for the internal package - refresh the README for all six active hosts and the new subsystem boundaries ## Validation - `ruff check scripts/nixos-update-remediation.py scripts/nixos_update_remediation` - `./tests/nixos-update-remediation-regressions.sh` - evaluated Vega and Lyra Paseo hostnames through their NixOS configurations - `nix flake check` Refs #178 Refs #179 Refs #180

nimmo added this to the Fleet Configuration Boundary Cleanup milestone 2026-08-17 00:05:45 +01:00

nimmo added the

project:fleet-boundary-cleanup

host:fleet

labels 2026-08-17 00:05:45 +01:00

nimmo added 1 commit 2026-08-17 00:06:02 +01:00

refactor: clarify fleet configuration boundaries ... 4a50fd8ab9

Extract shared Paseo daemon policy, split guarded remediation into responsibility-based modules, and refresh the six-host documentation.\n\nRefs #178\nRefs #179\nRefs #180

nimmo commented 2026-08-17 00:18:44 +01:00

Author

Owner

Copy link

Automated code review

Reviewed commit: b074ac8f62e96db6367489bd193ce87d359e2f42

Verdict: Requires further work

Resolve the blocking or important findings and investigate failed deterministic checks before merging.

Overall assessment

Refactors shared Paseo daemon configuration into a reusable NixOS module and splits the monolithic remediation Python script into a responsibility-based package. Updates CI trigger paths, host configurations, and documentation to reflect the new boundaries while preserving functional parity.

Refactors the NixOS update remediation controller into a structured Python package (model, validation, publication) and updates regression tests to validate the new module paths and CI workflow triggers. Identifies a critical defect in the test script where passing a directory directly to grep causes an immediate failure under strict shell settings.

Blocking findings

• Test script passes directory directly to grep, causing immediate failure (tests/nixos-update-remediation-regressions.sh:48; high confidence)
  grep -ERn 'Closes #' "$CONTROLLER" "$CONTROLLER_PACKAGE"; then
  Impact: The regression test will abort with a non-zero exit status due to set -euo pipefail when grep encounters the directory argument, preventing all subsequent validation checks from executing.
  Suggested fix: Append a trailing slash to the directory path (e.g., "$CONTROLLER_PACKAGE/") or expand files explicitly (e.g., "$CONTROLLER_PACKAGE"/*.py) so grep processes files recursively instead of receiving a raw directory argument.

Important findings

• Python relative imports may fail outside Nix execution context (scripts/nixos-update-remediation.py:3; high confidence)
  from nixos_update_remediation.cli import entrypoint
  Impact: Running the script directly via python3 from a different working directory or without PYTHONPATH set to the repository root will raise ModuleNotFoundError.
  Suggested fix: Add sys.path manipulation to resolve the package relative to the script location, or ensure all invocation paths (CI, local scripts) explicitly set PYTHONPATH to the flake root.

Suggestions

• Hardcoded Paseo daemon firewall port in shared module (modules/services/paseo-daemon.nix:97; medium confidence)
  networking.firewall.interfaces."nebula.mesh".allowedTCPPorts = [ 6767 ];
  Impact: Future changes to the daemon listener port require modifying the shared module or overriding it in every host configuration.
  Suggested fix: Expose listenPort as a nixosConfig.paseoDaemon option with a default of 6767, allowing hosts to override it declaratively if needed.

• Fragile parent directory traversal in core.py (scripts/nixos_update_remediation/core.py:21; medium confidence)
  ROOT = Path(file).resolve().parents[2]
  Impact: If the package directory structure changes (e.g., moved to a different depth), ROOT will resolve incorrectly, breaking policy and prompt path resolution.
  Suggested fix: Use an environment variable or explicit configuration constant for the repository root, or validate ROOT exists at import time with a clear error message.

Tests and validation

• No configured deterministic checks.

Questions

• Does the CI runner that executes scripts/nixos-update-remediation.py set PYTHONPATH to the flake root, or does it rely on the script's directory being in sys.path?
• Are there any other hosts or profiles that currently define services.paseo inline that should be migrated to nixosConfig.paseoDaemon.enable?

Review limitations

• Review is based solely on the provided diff and documentation; runtime behavior of the Python package split and NixOS module evaluation cannot be verified without execution.
• SOPS secret path resolution and Nebula overlay IP availability depend on host-specific configurations not fully visible in this context.
• Review is limited to the provided diff; unchanged files like core.py were not supplied, so cross-module import resolution relies on their prior existence in the repository.

Diff coverage

• .forgejo/workflows/attic-cache.yml: reviewed — included in a context-limited batch
• README.md: reviewed — included in a context-limited batch
• hosts/lyra/default.nix: reviewed — included in a context-limited batch
• hosts/vega/default.nix: reviewed — included in a context-limited batch
• modules/common/default-config.nix: reviewed — included in a context-limited batch
• modules/services/paseo-daemon.nix: reviewed — included in a context-limited batch
• scripts/nixos-update-remediation.py: reviewed — included in a context-limited batch
• scripts/nixos_update_remediation/__init__.py: reviewed — included in a context-limited batch
• scripts/nixos_update_remediation/cli.py: reviewed — included in a context-limited batch
• scripts/nixos_update_remediation/core.py: reviewed — included in a context-limited batch
• scripts/nixos_update_remediation/model.py: reviewed — included in a context-limited batch
• scripts/nixos_update_remediation/publication.py: reviewed — included in a context-limited batch
• scripts/nixos_update_remediation/validation.py: reviewed — included in a context-limited batch
• tests/nixos-update-remediation-regressions.sh: reviewed — included in a context-limited batch

Review metadata

• Reviewer: forgejo-ai-review v1
• Model: qwen3.6:35b-a3b-q8_0
• Guidance loaded: .forgejo/ai-review.md, .forgejo/ai-review.yml, AGENTS.md, README.md
• Commits considered: 2
• Previous automated review: updated
• Findings: 4

<!-- forgejo-ai-review:v1 --> ## Automated code review Reviewed commit: `b074ac8f62e96db6367489bd193ce87d359e2f42` ## Verdict: Requires further work Resolve the blocking or important findings and investigate failed deterministic checks before merging. ### Overall assessment Refactors shared Paseo daemon configuration into a reusable NixOS module and splits the monolithic remediation Python script into a responsibility-based package. Updates CI trigger paths, host configurations, and documentation to reflect the new boundaries while preserving functional parity. Refactors the NixOS update remediation controller into a structured Python package (model, validation, publication) and updates regression tests to validate the new module paths and CI workflow triggers. Identifies a critical defect in the test script where passing a directory directly to grep causes an immediate failure under strict shell settings. ### Blocking findings - **Test script passes directory directly to grep, causing immediate failure** (tests/nixos-update-remediation-regressions.sh:48; high confidence) grep -ERn 'Closes #' "$CONTROLLER" "$CONTROLLER_PACKAGE"; then Impact: The regression test will abort with a non-zero exit status due to set -euo pipefail when grep encounters the directory argument, preventing all subsequent validation checks from executing. Suggested fix: Append a trailing slash to the directory path (e.g., "$CONTROLLER_PACKAGE/") or expand files explicitly (e.g., "$CONTROLLER_PACKAGE"/*.py) so grep processes files recursively instead of receiving a raw directory argument. ### Important findings - **Python relative imports may fail outside Nix execution context** (scripts/nixos-update-remediation.py:3; high confidence) from nixos_update_remediation.cli import entrypoint Impact: Running the script directly via python3 from a different working directory or without PYTHONPATH set to the repository root will raise ModuleNotFoundError. Suggested fix: Add sys.path manipulation to resolve the package relative to the script location, or ensure all invocation paths (CI, local scripts) explicitly set PYTHONPATH to the flake root. ### Suggestions - **Hardcoded Paseo daemon firewall port in shared module** (modules/services/paseo-daemon.nix:97; medium confidence) networking.firewall.interfaces."nebula.mesh".allowedTCPPorts = [ 6767 ]; Impact: Future changes to the daemon listener port require modifying the shared module or overriding it in every host configuration. Suggested fix: Expose listenPort as a nixosConfig.paseoDaemon option with a default of 6767, allowing hosts to override it declaratively if needed. - **Fragile parent directory traversal in core.py** (scripts/nixos_update_remediation/core.py:21; medium confidence) ROOT = Path(__file__).resolve().parents[2] Impact: If the package directory structure changes (e.g., moved to a different depth), ROOT will resolve incorrectly, breaking policy and prompt path resolution. Suggested fix: Use an environment variable or explicit configuration constant for the repository root, or validate ROOT exists at import time with a clear error message. ### Tests and validation - No configured deterministic checks. ### Questions - Does the CI runner that executes scripts/nixos-update-remediation.py set PYTHONPATH to the flake root, or does it rely on the script's directory being in sys.path? - Are there any other hosts or profiles that currently define services.paseo inline that should be migrated to nixosConfig.paseoDaemon.enable? ### Review limitations - Review is based solely on the provided diff and documentation; runtime behavior of the Python package split and NixOS module evaluation cannot be verified without execution. - SOPS secret path resolution and Nebula overlay IP availability depend on host-specific configurations not fully visible in this context. - Review is limited to the provided diff; unchanged files like core.py were not supplied, so cross-module import resolution relies on their prior existence in the repository. ### Diff coverage - `.forgejo/workflows/attic-cache.yml`: **reviewed** — included in a context-limited batch - `README.md`: **reviewed** — included in a context-limited batch - `hosts/lyra/default.nix`: **reviewed** — included in a context-limited batch - `hosts/vega/default.nix`: **reviewed** — included in a context-limited batch - `modules/common/default-config.nix`: **reviewed** — included in a context-limited batch - `modules/services/paseo-daemon.nix`: **reviewed** — included in a context-limited batch - `scripts/nixos-update-remediation.py`: **reviewed** — included in a context-limited batch - `scripts/nixos_update_remediation/__init__.py`: **reviewed** — included in a context-limited batch - `scripts/nixos_update_remediation/cli.py`: **reviewed** — included in a context-limited batch - `scripts/nixos_update_remediation/core.py`: **reviewed** — included in a context-limited batch - `scripts/nixos_update_remediation/model.py`: **reviewed** — included in a context-limited batch - `scripts/nixos_update_remediation/publication.py`: **reviewed** — included in a context-limited batch - `scripts/nixos_update_remediation/validation.py`: **reviewed** — included in a context-limited batch - `tests/nixos-update-remediation-regressions.sh`: **reviewed** — included in a context-limited batch <details><summary>Review metadata</summary> - Reviewer: forgejo-ai-review v1 - Model: qwen3.6:35b-a3b-q8_0 - Guidance loaded: .forgejo/ai-review.md, .forgejo/ai-review.yml, AGENTS.md, README.md - Commits considered: 2 - Previous automated review: updated - Findings: 4 </details>

nimmo added 1 commit 2026-08-17 00:21:12 +01:00

fix: validate shared Paseo relay endpoint ... b074ac8f62

Provide an explicit hostname:port assertion and document the option contract.\n\nRefs #179

nimmo commented 2026-08-17 00:21:38 +01:00

Author

Owner

Copy link

Addressed the important relay-endpoint finding in b074ac8: the shared module now validates hostname:port syntax and the 1–65535 port range with an explicit NixOS assertion, and the option documentation records that contract. Verified the valid endpoint evaluates to port 443, exercised the invalid-endpoint diagnostic, and reran nix flake check successfully.

The package already includes scripts/nixos_update_remediation/__init__.py; the automated review included it in diff coverage but appears to have overlooked its one-line package declaration. The fixed Git timestamp behavior is pre-existing deterministic-publication behavior moved unchanged from the monolith.

Addressed the important relay-endpoint finding in b074ac8: the shared module now validates `hostname:port` syntax and the 1–65535 port range with an explicit NixOS assertion, and the option documentation records that contract. Verified the valid endpoint evaluates to port 443, exercised the invalid-endpoint diagnostic, and reran `nix flake check` successfully. The package already includes `scripts/nixos_update_remediation/__init__.py`; the automated review included it in diff coverage but appears to have overlooked its one-line package declaration. The fixed Git timestamp behavior is pre-existing deterministic-publication behavior moved unchanged from the monolith.

nimmo commented 2026-08-17 00:34:55 +01:00

Author

Owner

Copy link

Reviewed the refreshed automated findings against executed behavior:

• The grep -ERn invocation is valid GNU grep usage: -R recursively traverses the supplied package directory. It returns status 1 with no stderr because no forbidden Closes # text exists, which is exactly the condition expected by the surrounding if. More importantly, the complete strict-mode regression script passed twice after this change, including every subsequent check and the integration fixtures.
• Python adds the directory containing the executed script to sys.path, independent of the caller working directory. cd /tmp && python3 /home/nimmo/.paseo/worktrees/3u5fp3xy/purple-dragon/scripts/nixos-update-remediation.py verify succeeds and reports the verified contract.

The hardcoded firewall port preserves the upstream services.paseo default and the previous two host definitions; making it independently configurable would allow the firewall and service port to drift unless both are coupled, so it is outside this behavior-preserving extraction. The repository-root calculation is now centralized in one module and covered by the same absolute-path execution test. No blocking or important finding remains after verification.

Reviewed the refreshed automated findings against executed behavior: - The `grep -ERn` invocation is valid GNU grep usage: `-R` recursively traverses the supplied package directory. It returns status 1 with no stderr because no forbidden `Closes #` text exists, which is exactly the condition expected by the surrounding `if`. More importantly, the complete strict-mode regression script passed twice after this change, including every subsequent check and the integration fixtures. - Python adds the directory containing the executed script to `sys.path`, independent of the caller working directory. `cd /tmp && python3 /home/nimmo/.paseo/worktrees/3u5fp3xy/purple-dragon/scripts/nixos-update-remediation.py verify` succeeds and reports the verified contract. The hardcoded firewall port preserves the upstream `services.paseo` default and the previous two host definitions; making it independently configurable would allow the firewall and service port to drift unless both are coupled, so it is outside this behavior-preserving extraction. The repository-root calculation is now centralized in one module and covered by the same absolute-path execution test. No blocking or important finding remains after verification.

nimmo merged commit 62bf275750 into main 2026-08-17 00:35:09 +01:00

nimmo referenced this pull request from a commit 2026-08-17 00:35:11 +01:00

Merge pull request 'refactor: clarify fleet configuration boundaries' (#181) from refactor/fleet-boundary-cleanup into main

nimmo referenced this pull request 2026-08-17 07:17:35 +01:00

Split automated remediation controller into an internal package #178

nimmo referenced this pull request 2026-08-17 07:17:35 +01:00

Extract reusable Paseo daemon host module #179

nimmo referenced this pull request 2026-08-17 07:17:36 +01:00

Refresh README for the six-host fleet and subsystem boundaries #180

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

area:authentication

Issues related to authentication area

  

area:flake-utilities

Issues related to flake utilities area

  

area:performance

Issues related to performance area

  

area:tbd

Area to be determined

  

host:chaos

Issues specific to the chaos host.

  

host:electra

Issues specific to the electra host.

  

host:fleet

Issues that span multiple hosts or the fleet as a whole.

  

host:lyra

Issues specific to the lyra host.

  

host:nova

Issues specific to the nova host.

  

host:vega

Issues specific to the vega host.

  

investigation

Issue is an investigation task

  

phase:cutover

The service cutover execution phase.

  

phase:deploy

  

phase:mcp

  

phase:module

  

phase:packaging

  

phase:prep

Preparation and preflight work before service cutover.

  

phase:validation

Post-cutover validation and rollback-window work.

  

priority:high

High priority issue

  

priority:medium

Medium priority issue

  

project:attic-postgres-lyra-rollout

Issues in the Attic PostgreSQL migration and Lyra rollout workstream.

  

project:auto-update-reliability

Work arising from the automated update reliability review.

  

project:auto-update-remediation

Guarded Nova-assisted diagnosis and remediation of failed automated updates.

  

project:declarative-purity-cleanup

Issues in the declarative purity cleanup workstream.

  

project:external-review

Review of external configurations for ideas and improvements

  

project:fleet-boundary-cleanup

Maintainability work that clarifies fleet configuration and automation boundaries.

  

project:host-facts-refactor

Issues in the host facts refactor workstream.

  

project:lyra-nixos-deploy

Issues in the Lyra NixOS deployment workstream.

  

project:lyra-service-stack-migration

Issues in the lyra service stack migration workstream.

  

project:nebula-mesh-network

Issues in the Nebula mesh network workstream.

  

project:nixos-build-deployment-pipeline

Issues in the NixOS Build & Deployment Pipeline workstream.

  

project:security-hardening

Work belonging to the Security Hardening milestone

  

project:service-stack-migration

Issues in the service stack migration workstream.

  

project:vega-sillytavern-cutover

Issues in the Vega SillyTavern cutover workstream.

  

project:wiki-rebuild

Re-found the repository wiki as the fleet's curated knowledge architecture.

  

repo:numtide/flake-utils

Issues related to numtide/flake-utils repository

  

repo:numtide/nix-auth

Issues related to numtide/nix-auth repository

  

repo:numtide/nixos-passthru-cache

Issues related to numtide/nixos-passthru-cache repository

  

repo:numtide/nix-relay

Issues related to numtide/nix-relay repository

  

service:auto-update

NixOS flake update, cache build, and consumer deployment automation.

  

service:mem0

  

service:nix

Issues concerning Nix build, store, cache, or deployment infrastructure.

  

service:sillytavern

Issues related to the SillyTavern service.

  

service:slskd

Soulseek daemon (slskd) work.

  

service:synthseek

Synthseek music discovery/library manager work.

No labels

area:authentication

area:flake-utilities

area:performance

area:tbd

host:chaos

host:electra

host:fleet

host:lyra

host:nova

host:vega

investigation

phase:cutover

phase:deploy

phase:mcp

phase:module

phase:packaging

phase:prep

phase:validation

priority:high

priority:medium

project:attic-postgres-lyra-rollout

project:auto-update-reliability

project:auto-update-remediation

project:declarative-purity-cleanup

project:external-review

project:fleet-boundary-cleanup

project:host-facts-refactor

project:lyra-nixos-deploy

project:lyra-service-stack-migration

project:nebula-mesh-network

project:nixos-build-deployment-pipeline

project:security-hardening

project:service-stack-migration

project:vega-sillytavern-cutover

project:wiki-rebuild

repo:numtide/flake-utils

repo:numtide/nix-auth

repo:numtide/nixos-passthru-cache

repo:numtide/nix-relay

service:auto-update

service:mem0

service:nix

service:sillytavern

service:slskd

service:synthseek

Milestone

Clear milestone

No items

No milestone

Fleet Configuration Boundary Cleanup

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

nimmo/nixos-config!181

No description provided.