feat: /etc/conf.d file-based config with VFS mount

[joezhoujinjing]

Summary

• Introduce Linux-style /etc/conf.d/ brick configuration pattern
• New nexus.etc module — each brick calls get_brick_config("name") to load its own TOML config
• Auto-mount $STATE_DIR/etc as /etc in VFS (readonly) — config self-hosting
• NEXUS_STATE_DIR env var (default ~/.nexus) as the single bootstrap parameter
• nexus config init command to generate default conf.d files
• Ship default etc/conf.d/ files in repo (all commented out, self-documenting)
• POC: mount brick reads auto_sync from /etc/conf.d/mounts with env var fallback

Design

Boot sequence:

1. NEXUS_STATE_DIR → hardcode kernel paths (metastore, data, etc)
2. Boot kernel — zero config needed
3. Mount $STATE_DIR/etc → /etc (readonly PathLocalBackend)
4. Bricks call get_brick_config() to load their own /etc/conf.d/{name}

Each brick loads its own config (like Linux daemons), no factory coupling.
Precedence: CLI args > env vars (deprecated) > conf.d files > profile defaults.

Test plan

• 16 unit tests for nexus.etc (TOML loading, missing files, malformed TOML, env var resolution)
• 5 unit tests for /etc VFS mount (readonly, routing, skip when missing, conf.d integration)
• 130 deployment profile/boot tests still pass
• All pre-commit hooks pass (ruff, mypy, brick imports check)

🤖 Generated with Claude Code

[github-actions]

Type Safety Progress 📉

Current: 246 type: ignore comments
Baseline: 531 (Phase 3 start)
Change: -285

✅ Progress! Keep eliminating type suppressions!

[github-actions]

⚠️ Performance Alert ⚠️

Possible performance regression was detected for benchmark.
Benchmark result of this commit is worse than the previous benchmark result exceeding threshold 1.30.

Benchmark suite	Current: 8b69a15	Previous: 8cca243	Ratio
tests/benchmarks/test_core_operations.py::TestBulkOperationBenchmarks::test_write_batch_10	27.782551347008656 iter/sec (stddev: 0.0020315741473701343)	39.188778970248656 iter/sec (stddev: 0.001138536110711972)	1.41
tests/benchmarks/test_rebac_latency.py::TestL1CacheHit::test_l1_cache_hit_latency	16491.911506075077 iter/sec (stddev: 0.00000567799508504349)	29000.081830264273 iter/sec (stddev: 0.000003409453269809088)	1.76
tests/benchmarks/test_service_delegation.py::TestAsyncDelegationOverhead::test_version_get_delegation	6563.795088175207 iter/sec (stddev: 0.0000265085031658731)	8930.124477576594 iter/sec (stddev: 0.00003489369801859649)	1.36
tests/benchmarks/test_service_delegation.py::TestAsyncDelegationOverhead::test_rebac_check_delegation	6537.196394476286 iter/sec (stddev: 0.00002004745764648793)	8769.424929753402 iter/sec (stddev: 0.000028394751338990928)	1.34
tests/benchmarks/test_service_delegation.py::TestAsyncDelegationOverhead::test_mcp_list_mounts_delegation	6647.241220956916 iter/sec (stddev: 0.000023017785567831498)	8921.993016840954 iter/sec (stddev: 0.00003357628815439365)	1.34

This comment was automatically generated by workflow using github-action-benchmark.

[github-actions]

Type Safety Progress 📉

Current: 246 type: ignore comments
Baseline: 531 (Phase 3 start)
Change: -285

✅ Progress! Keep eliminating type suppressions!

[github-actions]

Type Safety Progress 📉

Current: 246 type: ignore comments
Baseline: 531 (Phase 3 start)
Change: -285

✅ Progress! Keep eliminating type suppressions!

[github-actions]

Type Safety Progress 📉

Current: 246 type: ignore comments
Baseline: 531 (Phase 3 start)
Change: -285

✅ Progress! Keep eliminating type suppressions!

[github-actions]

Type Safety Progress 📉

Current: 246 type: ignore comments
Baseline: 531 (Phase 3 start)
Change: -285

✅ Progress! Keep eliminating type suppressions!

[windoliver]

1. installed CLI builds will not have any default conf.d files, so both nexus config init and first-boot seeding break outside a source checkout.
   config_cmd.py line 49:49 and init.py line 540:540 assume repo-level etc/conf.d, but packaging only discovers src packages in pyproject.toml line 316:316. I
   built the wheel locally; it contained no etc/conf.d entries, _find_confd_source() returned None, and _seed_etc_defaults() created nothing.
2. /etc is described as read-only, but it is mounted writable. init.py line 495:495 says “readonly”, while init.py line 550:550 calls add_mount("/
   etc", etc_backend) without readonly=True. The router default is writable in router.py line 91:91, and write blocking only happens when that flag is set in
   router.py line 177:177. In standalone mode permissions are permissive by default in init.py line 369:369, so config can be mutated through the VFS.
3. bootstrapping /etc is not metadata-only; it rewrites every host file on startup. init.py line 553:553 says the backend write is “effectively a no-
   op”, but init.py line 561:561 calls sys_write(), which performs a real backend write in nexus_fs.py line 2054:2054, increments version in nexus_fs.py line
   2061:2061, and emits a write event in nexus_fs.py line 2087:2087. For PathLocalBackend, that becomes an actual file replace in path_backend.py line 140:140 and
   local_transport.py line 77:77.

Directionally, a nexus config command and file-backed brick config make sense for the CLI. I would not merge this version yet; it needs packaged defaults plus a
clear /etc contract: either truly readonly with metadata bootstrap, or intentionally writable with the docs/comments changed and startup no longer rewriting
files.