Merge FEATURE-ci-freebsd-toolchain-env: retain SDK identity through archive checks

Author: etr

scripts/run-v3-release-ci.py

@@ -60,6 +60,8 @@ def platform_proof(args):
     env = dict(os.environ, V3_RELEASE_IDENTITY=str(identity_path),
         V3_TLS_CFLAGS='-I' + (args.provider_prefix / 'include').as_posix(),
         V3_TLS_LIBS='-L' + (args.provider_prefix / 'lib').as_posix() + ' -lssl -lcrypto')
+    if args.toolchain_prefix:
+        env['V3_PACKAGE_TOOLCHAIN'] = str(args.toolchain_prefix)
     env['LD_LIBRARY_PATH'] = str(args.provider_prefix / 'lib')
     env['DYLD_LIBRARY_PATH'] = str(args.provider_prefix / 'lib')
     env['PATH'] = str(args.provider_prefix / 'bin') + os.pathsep + env['PATH']

scripts/test-v3-platform-ci.py

@@ -101,6 +101,130 @@ def test_compiler_wrapper_keeps_headers_and_runtime_through_clean_environment(se
 
 
 class SelectedPlatformEnvironment(unittest.TestCase):
+    class NativeChecksComplete(Exception):
+        pass
+
+    def native_checks(self, root, inherited_prefix=None, selected=True, dependency_selected=True):
+        """Run the archive orchestrator, real child/make and the production audit.
+
+        Only archive identity, the expensive package producer and native inspectors
+        are fixtures; this does not establish native FreeBSD ABI compatibility.
+        """
+        spec = importlib.util.spec_from_file_location('platform_native_checks', ROOT / 'scripts/run-v3-release-ci.py')
+        entrypoint = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(entrypoint)
+        sdk = root / 'selected sdk'
+        (sdk / 'lib').mkdir(parents=True)
+        (sdk / 'lib/libc++.so.1.0').touch()
+        source = root / 'source'
+        (source / 'scripts').mkdir(parents=True)
+        producer = source / 'scripts/check-v3-installed-consumer.py'
+        producer.write_text(textwrap.dedent('''\
+            import json, os, pathlib, shutil, sys
+            output = pathlib.Path(sys.argv[sys.argv.index('--output') + 1])
+            shutil.copytree(pathlib.Path(__file__).parents[2] / 'fixture', output)
+            (output / 'child.json').write_text(json.dumps({'argv': sys.argv[1:],
+                'prefix': os.environ.get('V3_PACKAGE_TOOLCHAIN')}))
+            # Like the package producer, selecting a runtime in this child cannot
+            # update the archive orchestrator's later make environment.
+            if '--toolchain-prefix' in sys.argv:
+                os.environ['V3_PACKAGE_TOOLCHAIN'] = sys.argv[sys.argv.index('--toolchain-prefix') + 1]
+            '''))
+        recipe = (ROOT / 'Makefile.am').read_text().split(
+            '\ncheck-v3-native-linkage:\n', 1)[1].split('\n\n', 1)[0]
+        for mode in ('no', 'yes'):
+            build = root / 'fixture' / ('tls-' + mode) / 'build'
+            (build / 'src/.libs').mkdir(parents=True)
+            (build / 'test').mkdir()
+            (build / 'src/.libs/libhttpserver_v3core.a').touch()
+            (build / 'test/native_linkage').write_text('#!/bin/sh\nexit 0\n')
+            (build / 'test/native_linkage').chmod(0o755)
+            (build / 'test/Makefile').write_text('TEST_LOGS = native_linkage.log\nnative_linkage:;@:\n')
+            (build / 'src/Makefile').write_text(
+                'libhttpserver.la:\n\tlibtool --tag=CXX --mode=link -o libhttpserver.la archive\n')
+            (build / 'Makefile').write_text(
+                'all:;@:\ncheck: check-v3-native-linkage\n'
+                'top_srcdir := ' + str(ROOT) + '\ntop_builddir := .\nabs_top_builddir := $(CURDIR)\n'
+                'enable_v3_tls := ' + mode + '\ncheck-v3-native-linkage:\n' + recipe + '\n')
+        tools = root / 'tools'
+        tools.mkdir()
+        # ldd uses whitespace-delimited paths; the alias resolves to the quoted SDK.
+        (root / 'sdk').symlink_to(sdk, target_is_directory=True)
+        dependency = root / ('sdk/lib/libc++.so.1.0' if dependency_selected else 'other/libc++.so.1.0')
+        for name, output in (('uname', 'FreeBSD'), ('nm', ''), ('ldd',
+                'libc++.so.1 => ' + str(dependency) + ' (0x1)\nlibcxxrt.so.1 => /lib/libcxxrt.so.1 (0x2)')):
+            tool = tools / name
+            tool.write_text("#!/bin/sh\ncat <<'OUTPUT'\n" + output + '\nOUTPUT\n')
+            tool.chmod(0o755)
+        if not dependency_selected:
+            dependency.parent.mkdir()
+            dependency.touch()
+        selection = root / 'selected.json'
+        selection.write_text(json.dumps(dict(commit='a' * 40, version='3.0.0', sha256='b' * 64,
+                                            source={}, files_sha256={})))
+        args = argparse.Namespace(selection=selection, output=root / 'output', archive=root / 'source.tar.gz',
+            provider_prefix=root / 'provider', compiler=str(sdk / 'bin/clang++'), cc='/llvm/bin/clang',
+            make=shutil.which('gmake') or shutil.which('make'), jobs=2, client_python=sys.executable,
+            node='node', pkg_config_dir=[], toolchain_prefix=sdk if selected else None)
+        release = dict(source_root=str(source), source={}, files_sha256={})
+        counts = dict(tests=1, checks=1)
+        gate = argparse.Namespace(expected_identity=lambda *args: {}, read_json=None)
+        env = dict(os.environ, PATH=str(tools) + os.pathsep + os.environ['PATH'])
+        env.pop('V3_PACKAGE_TOOLCHAIN', None)
+        if inherited_prefix is not None:
+            env['V3_PACKAGE_TOOLCHAIN'] = str(inherited_prefix)
+        with patch.object(entrypoint.platform, 'system', return_value='FreeBSD'), \
+                patch.object(entrypoint, 'validate_request'), \
+                patch.object(entrypoint.identity, 'source_identity', return_value={}), \
+                patch.object(entrypoint, 'selected_archive', return_value=release), \
+                patch.object(entrypoint, 'gate_runner', return_value=gate), \
+                patch.object(entrypoint.checks, 'validate_package', return_value=counts), \
+                patch.object(entrypoint.checks, 'automake_result', side_effect=[counts, self.NativeChecksComplete()]), \
+                patch.dict(os.environ, env, clear=True):
+            try:
+                entrypoint.platform_proof(args)
+            finally:
+                self.assertEqual(os.environ, env, 'archive proof must keep its selected SDK environment local')
+
+    @unittest.skipIf(os.name == 'nt', 'FreeBSD audit fixtures require POSIX scripts and GNU make')
+    def test_explicit_sdk_reaches_both_later_make_checks(self):
+        for inherited in (None, '/unselected/sdk'):
+            with self.subTest(inherited=inherited), tempfile.TemporaryDirectory() as directory:
+                root = Path(directory)
+                with self.assertRaises(self.NativeChecksComplete):
+                    self.native_checks(root, inherited_prefix=inherited)
+                commands = json.loads((root / 'output/commands.json').read_text())
+                checks = [command for command in commands if 'check' in command['argv']]
+                self.assertEqual(len(checks), 2)
+                for command in checks:
+                    self.assertEqual(command['exit'], 0)
+                    self.assertEqual(command['environment']['V3_PACKAGE_TOOLCHAIN'], str(root / 'selected sdk'))
+                    self.assertIn('A2 PASS', Path(command['log']).read_text())
+                child = json.loads((root / 'output/matrix/child.json').read_text())
+                self.assertEqual(child['prefix'], str(root / 'selected sdk'))
+                self.assertEqual(child['argv'][child['argv'].index('--toolchain-prefix') + 1], str(root / 'selected sdk'))
+                self.assertEqual(child['argv'][child['argv'].index('--compiler') + 1], str(root / 'selected sdk/bin/clang++'))
+                self.assertEqual(child['argv'][child['argv'].index('--cc') + 1], '/llvm/bin/clang')
+
+    @unittest.skipIf(os.name == 'nt', 'FreeBSD audit fixtures require POSIX scripts and GNU make')
+    def test_archive_checks_preserve_inherited_sdk_without_cli_override(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            with self.assertRaises(self.NativeChecksComplete):
+                self.native_checks(root, inherited_prefix=root / 'selected sdk', selected=False)
+
+    @unittest.skipIf(os.name == 'nt', 'FreeBSD audit fixtures require POSIX scripts and GNU make')
+    def test_archive_checks_reject_runtime_outside_explicit_sdk(self):
+        with tempfile.TemporaryDirectory() as directory:
+            with self.assertRaisesRegex(RuntimeError, 'unselected FreeBSD C[+][+] runtime'):
+                self.native_checks(Path(directory), dependency_selected=False)
+
+    @unittest.skipIf(os.name == 'nt', 'FreeBSD audit fixtures require POSIX scripts and GNU make')
+    def test_archive_checks_reject_missing_sdk_identity(self):
+        with tempfile.TemporaryDirectory() as directory:
+            with self.assertRaisesRegex(RuntimeError, 'selected FreeBSD C[+][+] runtime prefix missing'):
+                self.native_checks(Path(directory), selected=False)
+
     def test_native_platform_matrix_receives_matching_provider_cli(self):
         spec = importlib.util.spec_from_file_location('platform_ci_entrypoint', ROOT / 'scripts/run-v3-release-ci.py')
         entrypoint = importlib.util.module_from_spec(spec)

specs/tasks/FEATURE-ci-freebsd-toolchain-env.md

@@ -0,0 +1,74 @@
+# FEATURE-ci-freebsd-toolchain-env: retain selected SDK identity through archive native checks
+
+Status: Complete — local implementation and validation complete; native execution remains CI/v3-PR owned.
+Base: `v3` at `831aad155b9c4f0350b6376e2f589379039022d2`.
+Plan: `.groundwork-plans/FEATURE-ci-freebsd-toolchain-env-plan.md` in the primary checkout.
+Journal: `.debug/ci-freebsd-toolchain-env-b_nxofo9/journal.md` in the primary checkout.
+Requirements: the existing complete selected SDK contract and native packaging
+checks in `specs/architecture/v3/architecture.md`, with strict runtime ownership
+under `PRD-V3N-REQ-002/003`.
+
+Action items:
+
+- [x] Read the accepted plan, literal journal, primary CLAUDE.md, applicable AGENTS
+  and relevant selected SDK/workflow/runner/native audit sources.
+- [x] Create the assigned isolated worktree from the exact local v3 base and
+  preserve unrelated work.
+- [x] Prove the missing handoff with the production archive orchestrator,
+  production command runner, real child process, GNU make and native audit.
+- [x] Select the explicit CLI SDK prefix in the archive runner's local subprocess
+  environment so the matrix and both later TLS-mode native checks agree.
+- [x] Verify explicit CLI precedence, inherited selection without a CLI override,
+  quoted prefixes, missing identity rejection and rejection of another runtime.
+- [x] Retain compiler/C compiler CLI selection, strict audits, complete archive
+  checks and process-local SDK selection without Node/provider C flag changes.
+- [x] Run affected existing tests, Python syntax and whitespace checks.
+- [x] Caller: full Groundwork validation, finalization, merge and cleanup.
+- [ ] Native FreeBSD post-repair execution: CI/v3-PR owned, not executed locally.
+
+The sourced FreeBSD `toolchain.env` supplies shell assignments, while the workflow
+passes their values explicitly to the archive runner. That runner previously
+forwarded `--toolchain-prefix` only to its child package matrix. Runtime selection
+inside that child cannot update the parent environment, so later `gmake check`
+lost `V3_PACKAGE_TOOLCHAIN`; the existing strict native audit then rejected the
+private libc++ runtime. A conflicting inherited prefix could likewise disagree
+with the explicit CLI selection. The repair belongs in `platform_proof`, which
+owns the environment shared by its matrix and subsequent make commands.
+
+The test-first execution reproduced `selected FreeBSD C++ runtime prefix missing`
+at the actual later `gmake check -j2` boundary. With a stale inherited prefix it
+reproduced `invalid C++ runtime prefix`. After the two-line repair both TLS-off
+and TLS-on native audit recipes pass through real GNU make with controlled
+FreeBSD `uname`/`ldd`/`nm` fixtures. Separate cases preserve inherited selection
+when no CLI prefix is given and reject missing or foreign selected runtimes.
+The regression also checks that the runner leaves `os.environ` unchanged.
+
+Verification:
+
+- Focused baseline: 5 existing platform environment/FreeBSD selector tests pass.
+- `python3 scripts/test-v3-platform-ci.py`: 15 pass.
+- `python3 scripts/test-v3-native-linkage.py`: 21 pass.
+- `python3 scripts/test-v3-ci-workflows.py FreeBSDNodePrerequisites`: 6 pass,
+  including the unchanged Node/provider environment contract in both workflows.
+- Changed Python files pass `python3 -m py_compile`; `git diff --check` passes.
+  CLAUDE's C++ cpplint does not apply to these Python/Markdown changes. No
+  workflow changed, so actionlint is not an affected check.
+
+RED/GREEN output and a durable real command/native audit trace are retained in
+the primary checkout under
+`.debug/ci-freebsd-toolchain-env-b_nxofo9/implementation/`; the durable trace is
+`native-boundary/output/commands.json`. The package-producing fixture replaces
+the expensive native matrix, and archive identity/count aggregation are controlled
+test inputs; these runs prove environment propagation and strict audit behavior,
+not native FreeBSD compilation, execution or libcxxrt ABI compatibility. Native
+post-repair CI and overall CI-green status remain incomplete.
+
+The predecessor SDK validation remains sealed and unchanged. Existing local
+LLVM20 cancellation/compiler/runtime evidence remains valid without rebuilding
+the SDK. No full baseline, old validation restart, unrelated failure investigation,
+new native CI run, publication, push or merge was performed. Previously closed
+Darwin/Linux/Windows uncertainty batches remain closed.
+
+Final local validation/finalization (2026-10-23):
+
+Groundwork sealed exact clean implementation `f7326d37b4553c4dbe526379317390da86bfa41b` / tree `e95f2b2316eb055ff356476079eadbcb4b7fe82d`: 1 iteration, 0 fixed, 0 unworked. Eight current reviewers approved; the unchanged performance approval was carried from the sealed SDK predecessor, accounting for all nine applicable profiles. Durable receipt: `.git/groundwork/validation/cdb4ee2aea69cc6a/dc47aaed14db8e41/groundwork-validation-0f8a5a6aee0724d7cb9cc71ce24b8aec`. The earlier implementation-only paragraph is superseded for local validation/finalization. Caller changes only this bookkeeping before serial merge/cleanup. The concrete archive environment defect identified in the predecessor SDK review is repaired here; its historical sealed report and other unworked observations remain unchanged. Native FreeBSD/libcxxrt and post-repair platform outcomes remain unexecuted locally and assigned to CI/v3 PR. Overall CI-green work remains open pending fresh CI.