From dd44c1eafc5282315bd42c9fee33c18cc39f46ee Mon Sep 17 00:00:00 2001 From: Thorsten Fuchs <76904008+ThorFuchs@users.noreply.github.com> Date: Wed, 11 Nov 2026 14:55:46 +0100 Subject: [PATCH 1/3] Add platform-floor CI lane; exclude DocC catalogs from CLI identity The platform-floor native lane checks the macOS 15 / iOS 18 manifest minimums, cross-compiles every library for iOS 18 device and simulator, and builds and runs Tools/PlatformFloorConsumer, an external consumer that declares the same minimums and exercises each product. The CLI source identity now skips *.docc catalogs, which do not affect the executable, so documentation-only edits no longer need a regenerated identity. The harness covers the new exclusion. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/native.yml | 2 +- CHANGELOG.md | 12 +++ Documentation/CLI.md | 3 +- Documentation/Qualification/Release1.9.md | 3 +- Scripts/README.md | 1 + Scripts/ci.py | 4 +- Scripts/generate_cli_identity.py | 9 +- Scripts/qualify_platform_floor.py | 67 ++++++++++++++ Scripts/test_qualification_harness.py | 5 +- Sources/JSONCLIEngine/CLIBuildIdentity.swift | 4 +- Tools/PlatformFloorConsumer/Package.swift | 30 ++++++ .../Sources/FloorProbe/FloorProbe.swift | 91 +++++++++++++++++++ .../Sources/PlatformFloorConsumer/main.swift | 5 + 13 files changed, 226 insertions(+), 10 deletions(-) create mode 100644 Scripts/qualify_platform_floor.py create mode 100644 Tools/PlatformFloorConsumer/Package.swift create mode 100644 Tools/PlatformFloorConsumer/Sources/FloorProbe/FloorProbe.swift create mode 100644 Tools/PlatformFloorConsumer/Sources/PlatformFloorConsumer/main.swift diff --git a/.github/workflows/native.yml b/.github/workflows/native.yml index efed818..0a219b6 100644 --- a/.github/workflows/native.yml +++ b/.github/workflows/native.yml @@ -17,7 +17,7 @@ jobs: strategy: fail-fast: false matrix: - lane: [native, safety, docs, archive, composition] + lane: [native, safety, docs, archive, composition, platform-floor] env: DEVELOPER_DIR: /Applications/Xcode_27.2.app/Contents/Developer PYTHONDONTWRITEBYTECODE: '1' diff --git a/CHANGELOG.md b/CHANGELOG.md index 5a4905c..3db4883 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,17 @@ # Changelog +## Unreleased — 1.9.1 hygiene + +- Add the `platform-floor` native CI lane. It checks the macOS 15 / iOS 18 + manifest minimums, cross-compiles all twelve libraries for iOS 18 devices and + the iOS simulator, and builds and runs `Tools/PlatformFloorConsumer`, an + external consumer declaring the same minimums. Runtime tests on macOS 15-26 or + iOS 18 systems remain outside CI. +- The CLI source identity no longer covers DocC catalogs (`*.docc`), so + documentation-only edits no longer require regenerating it. +- Repository housekeeping: superseded remote branches removed; branches without a + PR were first preserved as `archive/` tags. + ## 1.9.0 — prepared source; publication separate - Report CLI source version `1.9.0` with a regenerated deterministic source diff --git a/Documentation/CLI.md b/Documentation/CLI.md index 9436c4a..35fdf12 100644 --- a/Documentation/CLI.md +++ b/Documentation/CLI.md @@ -70,7 +70,8 @@ swift run swift-json --version --json Human output identifies the source version. JSON adds `revisionKind` with value `source-sha256`; `revision` is `sha256:` plus a lowercase 64-digit digest. This digest hashes the ordered content manifest for `Package.swift` and every file in -`Sources`, excluding only generated `CLIBuildIdentity.swift`. The manifest uses +`Sources`, excluding generated `CLIBuildIdentity.swift` and DocC catalogs +(`*.docc`), which are documentation rather than compiled source. The manifest uses UTF-8 relative paths and SHA-256 file digests. It is a source-content identity, not a Git commit, binary digest, wall-clock build ID or assertion of publication. diff --git a/Documentation/Qualification/Release1.9.md b/Documentation/Qualification/Release1.9.md index 42cce6c..fca8cef 100644 --- a/Documentation/Qualification/Release1.9.md +++ b/Documentation/Qualification/Release1.9.md @@ -48,7 +48,8 @@ Evidence is compile-time only, on `49d1c93` with Swift 6.4.2: No test has run on an actual macOS 15–26 or iOS 18 system or simulator, and this record claims no such runtime pass. CI checks the manifest minimums but does not -build for iOS. +build for iOS. After the release, the `platform-floor` lane (1.9.1 hygiene) added +this compile-time evidence to CI; it still runs nothing on an older OS. ## Performance gate: maintainer exception diff --git a/Scripts/README.md b/Scripts/README.md index 5d5e469..3521f68 100644 --- a/Scripts/README.md +++ b/Scripts/README.md @@ -8,6 +8,7 @@ separate from the dependency-free library. Native lanes fail on unsupported host | `python3 Scripts/public_check.py` | Public inventory, links, baseline and finite profiles | | `python3 Scripts/preflight.py` | Actual native OS/compiler/SDK receipt | | `python3 Scripts/ci.py --lane native` | Manifests, builds, Swift Testing, consumers and suites | +| `python3 Scripts/ci.py --lane platform-floor` | Manifest minimums macOS 15 / iOS 18, every library cross-compiled for iOS 18 device and simulator, and an external consumer at those minimums built for iOS and run on macOS (Debug/Release) | | `python3 Scripts/ci.py --lane safety` | Address/Thread Sanitizer and strict memory safety | | `python3 Scripts/ci.py --lane navigation` | N1 product exact discovery, Debug/Release, strict-memory and real external SwiftPM consumer/compiler/DocC proof; no release action | | `python3 Scripts/ci.py --lane linux` | Actual Linux preflight, all nine products, exact root/cap/corpus/consumer counts | diff --git a/Scripts/ci.py b/Scripts/ci.py index b939bc7..5e88a5d 100644 --- a/Scripts/ci.py +++ b/Scripts/ci.py @@ -242,6 +242,8 @@ def portable(values): ['python3', '-B', 'Scripts/qualify_cli_integration.py', '--binary', '.build/release/swift-json', '--output', str(output / 'integration-subprocess.json')], ['python3', '-B', 'Scripts/qualify_cli_limits.py', '--binary', '.build/release/swift-json', '--output', str(output / 'cli-limits.json')], ['swift', 'build', '-c', 'release', '--package-path', 'Tools/CLIQualification', '--product', 'CLIExactCompare'], ['python3', '-B', 'Scripts/qualify_cli_cases.py', '--binary', '.build/release/swift-json', '--comparator', 'Tools/CLIQualification/.build/release/CLIExactCompare', '--gate', 'C1', '--output', str(output / 'foundation-vectors.json')], ['python3', '-B', 'Scripts/qualify_cli_cases.py', '--binary', '.build/release/swift-json', '--comparator', 'Tools/CLIQualification/.build/release/CLIExactCompare', '--gate', 'C2', '--output', str(output / 'vectors.json')], ['python3', '-B', 'Scripts/qualify_cli_cases.py', '--binary', '.build/release/swift-json', '--comparator', 'Tools/CLIQualification/.build/release/CLIExactCompare', '--gate', 'C3', '--output', str(output / 'arithmetic-vectors.json')], ['python3', '-B', 'Scripts/qualify_cli_cases.py', '--binary', '.build/release/swift-json', '--comparator', 'Tools/CLIQualification/.build/release/CLIExactCompare', '--gate', 'C4', '--output', str(output / 'advanced-vectors.json')], ['python3', '-B', 'Scripts/qualify_cli_cases.py', '--binary', '.build/release/swift-json', '--comparator', 'Tools/CLIQualification/.build/release/CLIExactCompare', '--gate', 'C5', '--output', str(output / 'integration-vectors.json')], ['swift', 'run', '-c', 'release', '--package-path', 'Tools/CLIQualification', 'ProviderConsumer'], ['python3', '-B', 'Scripts/qualify_schema_providers.py', '--binary', '.build/release/swift-json', '--output', str(output / 'providers.json')]] + if lane == 'platform-floor': + return [['python3', '-B', 'Scripts/qualify_platform_floor.py', '--output', str(output / 'platform-floor')]] if lane == 'native': return [ ['python3', '-B', 'Scripts/public_check.py'], @@ -544,7 +546,7 @@ def check_result(command, code, log, events=None): def main(): parser = argparse.ArgumentParser(description=__doc__) - parser.add_argument('--lane', choices=['transform-bindings', 'transform-bindings-safety', 'structural-acceptance', 'structural-acceptance-safety', 'structural-workflows', 'structural-workflows-safety', 'store', 'store-preparation', 'composition', 'navigation', 'inspection', 'native', 'safety', 'docs', 'r0', 'qa', 'linux', 'linux-safety', 'wasm', 'browser', 'export', 'cli', 'schema-examples', 'schema-examples-safety', 'schema-examples-determinism', 'schema-examples-construction', 'schema-examples-advanced', 'schema-examples-qualification', 'coverage', 'linux-coverage', 'linux-qa', 'wasm-qa', 'archive'], required=True) + parser.add_argument('--lane', choices=['transform-bindings', 'transform-bindings-safety', 'structural-acceptance', 'structural-acceptance-safety', 'structural-workflows', 'structural-workflows-safety', 'store', 'store-preparation', 'composition', 'navigation', 'inspection', 'native', 'safety', 'docs', 'r0', 'qa', 'linux', 'linux-safety', 'wasm', 'browser', 'export', 'cli', 'schema-examples', 'schema-examples-safety', 'schema-examples-determinism', 'schema-examples-construction', 'schema-examples-advanced', 'schema-examples-qualification', 'coverage', 'linux-coverage', 'linux-qa', 'wasm-qa', 'archive', 'platform-floor'], required=True) parser.add_argument('--output') parser.add_argument('--skip-host-measurements', action='store_true', help='For WASI runtime qualification only: record optional host timings as NOT RUN.') args = parser.parse_args() diff --git a/Scripts/generate_cli_identity.py b/Scripts/generate_cli_identity.py index 54bc83d..04a76ae 100644 --- a/Scripts/generate_cli_identity.py +++ b/Scripts/generate_cli_identity.py @@ -14,7 +14,10 @@ def rendered(root=ROOT): paths = [root / 'Package.swift'] + sorted((root / 'Sources').rglob('*')) records = [] for path in paths: - if not path.is_file() or path.relative_to(root) == GENERATED: + relative = path.relative_to(root) + # DocC catalogs are documentation, not compiled source; editing them does not + # change the executable, so they are outside the source identity. + if not path.is_file() or relative == GENERATED or any(part.endswith('.docc') for part in relative.parts): continue if path.is_symlink(): raise ValueError('Source identity cannot follow symlinks') @@ -22,7 +25,7 @@ def rendered(root=ROOT): value = hashlib.sha256(''.join(records).encode()).hexdigest() return ('// SPDX-License-Identifier: Apache-2.0\n' '// Generated by Scripts/generate_cli_identity.py; excludes this file.\n' - '// SHA-256 of the ordered Package.swift + Sources content manifest, not a Git commit.\n' + '// SHA-256 of the ordered Package.swift + Sources content manifest (DocC catalogs excluded), not a Git commit.\n' 'package enum CLIBuildIdentity {\n' ' package static let revision = "sha256:' + value + '"\n' ' package static let kind = "source-sha256"\n' @@ -41,7 +44,7 @@ def main(): return 1 else: path.write_text(expected) - print('CLI_IDENTITY passed source_manifest=Package.swift+Sources git_required=false') + print('CLI_IDENTITY passed source_manifest=Package.swift+Sources-without-docc git_required=false') return 0 diff --git a/Scripts/qualify_platform_floor.py b/Scripts/qualify_platform_floor.py new file mode 100644 index 0000000..f065724 --- /dev/null +++ b/Scripts/qualify_platform_floor.py @@ -0,0 +1,67 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: Apache-2.0 +"""Compile-time evidence for the declared Apple deployment minimums (macOS 15, iOS 18). + +Checks the manifest minimums, cross-compiles every library product for iOS devices and +the iOS simulator at iOS 18, and builds and runs an external consumer that declares the +same minimums. It does not run anything on an older OS; that remains outside CI. +""" +import argparse, hashlib, json, os, pathlib, subprocess, sys + +ROOT = pathlib.Path(__file__).resolve().parents[1] +CONSUMER = 'Tools/PlatformFloorConsumer' +LIBRARIES = ['JSON', 'JSONSchema', 'JSONSchemaExamples', 'JSONStreaming', 'JSONPatch', 'JSONHTML', 'JSONBridges', + 'JSONNavigation', 'JSONInspection', 'JSONTransform', 'JSONValueDSL', 'JSONSchemaDSL'] +EXPECTED_PLATFORMS = [{'options': [], 'platformName': 'macos', 'version': '15.0'}, + {'options': [], 'platformName': 'ios', 'version': '18.0'}] +WITNESS = 'PLATFORM_FLOOR passed witnesses=8' + + +def sdk_path(name): + return subprocess.check_output(['xcrun', '--sdk', name, '--show-sdk-path'], text=True).strip() + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument('--output', required=True) + args = parser.parse_args() + output = (ROOT / args.output).resolve(); output.mkdir(parents=True, exist_ok=True) + receipt = dict(status='failed', commands=[], libraries=LIBRARIES, platforms=EXPECTED_PLATFORMS) + + def run(name, command, env=None, cwd=ROOT): + result = subprocess.run(command, cwd=cwd, capture_output=True, text=True, env=env, timeout=1800) + log = output / (name + '.log'); log.write_text(result.stdout + result.stderr) + receipt['commands'].append(dict(name=name, command=command, exit=result.returncode, + log=log.name, sha256=hashlib.sha256(log.read_bytes()).hexdigest())) + print(name, result.returncode, flush=True) + if result.returncode != 0: + raise RuntimeError(name) + return result.stdout + + try: + manifest = json.loads(run('manifest', ['swift', 'package', 'dump-package'])) + if manifest['platforms'] != EXPECTED_PLATFORMS: + raise RuntimeError('manifest platforms ' + json.dumps(manifest['platforms'])) + for sdk, triple, scratch in [('iphoneos', 'arm64-apple-ios18.0', 'ios'), + ('iphonesimulator', 'arm64-apple-ios18.0-simulator', 'ios-simulator')]: + env = dict(os.environ, SDKROOT=sdk_path(sdk)) + for library in LIBRARIES: + run(scratch + '-' + library, ['swift', 'build', '--target', library, '--triple', triple, '--sdk', env['SDKROOT'], + '--scratch-path', '.build/platform-floor/' + scratch], env=env) + run(scratch + '-consumer', ['swift', 'build', '--package-path', CONSUMER, '--target', 'FloorProbe', '--triple', triple, + '--sdk', env['SDKROOT'], '--scratch-path', CONSUMER + '/.build/' + scratch], env=env) + for config in ['debug', 'release']: + stdout = run('macos-consumer-' + config, ['swift', 'run', '--package-path', CONSUMER, '-c', config, + '--scratch-path', CONSUMER + '/.build/macos', 'PlatformFloorConsumer']) + if stdout.strip().splitlines()[-1:] != [WITNESS]: + raise RuntimeError('consumer witness ' + config) + receipt['status'] = 'passed' + except (RuntimeError, subprocess.SubprocessError, OSError, KeyError, ValueError) as error: + receipt['error'] = str(error) + (output / 'receipt.json').write_text(json.dumps(receipt, indent=1) + '\n') + print(json.dumps(dict(status=receipt['status'], commands=len(receipt['commands']), libraries=len(LIBRARIES)))) + return 0 if receipt['status'] == 'passed' else 1 + + +if __name__ == '__main__': + sys.exit(main()) diff --git a/Scripts/test_qualification_harness.py b/Scripts/test_qualification_harness.py index b41bea0..63f0999 100644 --- a/Scripts/test_qualification_harness.py +++ b/Scripts/test_qualification_harness.py @@ -38,7 +38,7 @@ def workflow_jobs(self, filename): def test_required_workflow_contexts_wait_for_complete_execution_matrices(self): for filename, execution, required, name in [ - ('native.yml','[native, safety, docs, archive, composition]','[native, safety, docs, archive]','Native / ${{ matrix.lane }}'), + ('native.yml','[native, safety, docs, archive, composition, platform-floor]','[native, safety, docs, archive]','Native / ${{ matrix.lane }}'), ('linux.yml','[linux, linux-safety, composition]','[linux, linux-safety]','Linux / ${{ matrix.architecture }} / ${{ matrix.lane }}'), ]: with self.subTest(workflow=filename): @@ -593,6 +593,9 @@ def test_cli_identity_ignores_git_time_and_generated_output_but_detects_source_c (self.root / '.git').mkdir(); (self.root / '.git/HEAD').write_text('unrelated') (source / 'CLIBuildIdentity.swift').write_text('previous generated value') self.assertEqual(rendered(self.root), first) + catalog = self.root / 'Sources/JSONCLIEngine/Documentation.docc'; catalog.mkdir() + (catalog / 'Guide.md').write_text('# Documentation-only change\n') + self.assertEqual(rendered(self.root), first) owned.write_text('let version = "1.5.2"\n') self.assertNotEqual(rendered(self.root), first) diff --git a/Sources/JSONCLIEngine/CLIBuildIdentity.swift b/Sources/JSONCLIEngine/CLIBuildIdentity.swift index f560b08..d2437cc 100644 --- a/Sources/JSONCLIEngine/CLIBuildIdentity.swift +++ b/Sources/JSONCLIEngine/CLIBuildIdentity.swift @@ -1,7 +1,7 @@ // SPDX-License-Identifier: Apache-2.0 // Generated by Scripts/generate_cli_identity.py; excludes this file. -// SHA-256 of the ordered Package.swift + Sources content manifest, not a Git commit. +// SHA-256 of the ordered Package.swift + Sources content manifest (DocC catalogs excluded), not a Git commit. package enum CLIBuildIdentity { - package static let revision = "sha256:43e6285a7d265092fc1f29d9919cfa297a1f96d074d40f1e12be7a8d2734a453" + package static let revision = "sha256:3b65f6ca79902befb4c50649094739bf30838631c2f2fbc46515c2c6df64e164" package static let kind = "source-sha256" } diff --git a/Tools/PlatformFloorConsumer/Package.swift b/Tools/PlatformFloorConsumer/Package.swift new file mode 100644 index 0000000..e7e304d --- /dev/null +++ b/Tools/PlatformFloorConsumer/Package.swift @@ -0,0 +1,30 @@ +// swift-tools-version: 6.4 +// SPDX-License-Identifier: Apache-2.0 +import PackageDescription + +// Declares exactly the package's deployment minimums so the compiler enforces +// availability of every public API a consumer reaches at that floor. +let package = Package( + name: "PlatformFloorConsumer", + platforms: [.macOS(.v15), .iOS(.v18)], + products: [.executable(name: "PlatformFloorConsumer", targets: ["PlatformFloorConsumer"])], + dependencies: [.package(name: "Swift-JSON", path: "../..")], + targets: [ + .target(name: "FloorProbe", dependencies: [ + .product(name: "JSON", package: "Swift-JSON"), + .product(name: "JSONSchema", package: "Swift-JSON"), + .product(name: "JSONSchemaExamples", package: "Swift-JSON"), + .product(name: "JSONStreaming", package: "Swift-JSON"), + .product(name: "JSONPatch", package: "Swift-JSON"), + .product(name: "JSONHTML", package: "Swift-JSON"), + .product(name: "JSONBridges", package: "Swift-JSON"), + .product(name: "JSONNavigation", package: "Swift-JSON"), + .product(name: "JSONInspection", package: "Swift-JSON"), + .product(name: "JSONTransform", package: "Swift-JSON"), + .product(name: "JSONValueDSL", package: "Swift-JSON"), + .product(name: "JSONSchemaDSL", package: "Swift-JSON"), + ]), + .executableTarget(name: "PlatformFloorConsumer", dependencies: ["FloorProbe"]), + ], + swiftLanguageModes: [.v6] +) diff --git a/Tools/PlatformFloorConsumer/Sources/FloorProbe/FloorProbe.swift b/Tools/PlatformFloorConsumer/Sources/FloorProbe/FloorProbe.swift new file mode 100644 index 0000000..ced8b3d --- /dev/null +++ b/Tools/PlatformFloorConsumer/Sources/FloorProbe/FloorProbe.swift @@ -0,0 +1,91 @@ +// SPDX-License-Identifier: Apache-2.0 +// Public-API probe compiled at the macOS 15 / iOS 18 floor and run on the host. +import Foundation +import JSON +import JSONSchema +import JSONSchemaExamples +import JSONStreaming +import JSONPatch +import JSONHTML +import JSONBridges +import JSONNavigation +import JSONInspection +import JSONTransform +import JSONValueDSL +import JSONSchemaDSL + +private struct OneChunk: AsyncSequence, Sendable { + let bytes: [UInt8] + func makeAsyncIterator() -> Iterator { Iterator(bytes: bytes) } + struct Iterator: AsyncIteratorProtocol { + var bytes: [UInt8]? + mutating func next() async -> JSONByteChunk? { + guard let chunk = bytes else { return nil } + bytes = nil + return JSONByteChunk(chunk) + } + } +} + +/// Runs one witness per product and returns the number of passed witnesses. +public func runFloorProbe() async throws -> Int { + var passed = 0 + let value = try JSON.parse(#"{"orders":[{"id":7,"next":null}],"present":1,"list":[1,2]}"#) + + // JSONSchema + let plan = try JSONSchemaCompiler().compile(JSONSchemaDocument(JSON.parse(#"{"type":"integer","minimum":0}"#))) + let validation = try plan.validate(42) + precondition(validation.isValid) + passed += 1 + + // JSONPatch + let patch = try JSONPatch(operations: [.remove(path: JSONPointer(parsing: "/present")), + .add(path: JSONPointer(parsing: "/list/-"), value: 3)]) + let patched = try patch.applying(to: value) + let expectedPatch = try JSON.parse(#"{"orders":[{"id":7,"next":null}],"list":[1,2,3]}"#) + precondition(patched == .document(expectedPatch)) + passed += 1 + + // JSONStreaming + var located = 0 + for try await event in JSONLocatedTopLevelArraySequence(OneChunk(bytes: Array("[1,{\"a\":2},[]]".utf8))) { + if case .element = event { located += 1 } + } + precondition(located == 3) + passed += 1 + + // JSONNavigation + let nodes = try JSONTraversal(document: .init(root: value)).collect(scope: .subtree(at: [.key("orders")])).result.nodes + precondition(!nodes.isEmpty) + passed += 1 + + // JSONInspection + let document = try JSONParser().parseDocument(Data(#"{"orders":[{"id":7,"next":null}]}"#.utf8)) + let profile = JSONStoreProfile(version: .v1, collectionsAt: [], collections: [ + .init(name: "orders", recordsAt: [.key("orders")], idKey: "id", idKind: .integer, + referenceFields: [.init(key: "next", presence: .required, nullable: true)]) + ], references: .strict(marker: .v1)) + let store = try JSONStoreBuilder(document: document, profile: profile).build().result + let found = try store.lookup(collection: "orders", id: 7).result + precondition(found != nil) + passed += 1 + + // JSONTransform + let selection = try JSONTransformProgramDefinition.prepare(source: ".[] | select($values[.] > 1)", variables: ["values"]) + .result.compile().result + let indices = try selection.selectIndices(in: [1, 2, 3]).result + precondition(indices == [1, 2]) + passed += 1 + + // JSONHTML + let html = try JSONHTMLRenderer().renderWithReport(value) + precondition(html.statistics.documentBytes > 0 && !html.result.isEmpty) + passed += 1 + + // JSONBridges + let decimal = try Decimal(jsonNumber: JSONNumber(parsing: "0.1")) + precondition(decimal == Decimal(string: "0.1")) + passed += 1 + + return passed +} diff --git a/Tools/PlatformFloorConsumer/Sources/PlatformFloorConsumer/main.swift b/Tools/PlatformFloorConsumer/Sources/PlatformFloorConsumer/main.swift new file mode 100644 index 0000000..06a510c --- /dev/null +++ b/Tools/PlatformFloorConsumer/Sources/PlatformFloorConsumer/main.swift @@ -0,0 +1,5 @@ +// SPDX-License-Identifier: Apache-2.0 +import FloorProbe + +let passed = try await runFloorProbe() +print("PLATFORM_FLOOR passed witnesses=\(passed)") From 0495e6fdf00413948db9ff1b0cadaea346986114 Mon Sep 17 00:00:00 2001 From: "Dr. Thorsten Fuchs" Date: Wed, 11 Nov 2026 18:57:00 +0100 Subject: [PATCH 2/3] Repair Linux CI bootstrap and preserve archive timeout evidence (#91) * Diagnose CI DNS and preserve archive timeout evidence * Probe pinned Python setup on both Linux runners * Use pinned Python tool cache for Linux qualification * Retain primary archive timeout when cleanup fails * Give full native and archive qualification bounded headroom --- .github/workflows/linux.yml | 10 ++- .github/workflows/native.yml | 13 +++- Documentation/Qualification/MaintenanceCI.md | 27 ++++++- Scripts/ci.py | 4 +- Scripts/qualify_native_reproduction.py | 45 +++++++++-- Scripts/test_native_reproduction_timeout.py | 81 ++++++++++++++++++++ Scripts/test_qualification_harness.py | 15 +++- 7 files changed, 179 insertions(+), 16 deletions(-) create mode 100644 Scripts/test_native_reproduction_timeout.py diff --git a/.github/workflows/linux.yml b/.github/workflows/linux.yml index 9a2349c..4975447 100644 --- a/.github/workflows/linux.yml +++ b/.github/workflows/linux.yml @@ -30,12 +30,14 @@ jobs: env: PYTHONDONTWRITEBYTECODE: '1' steps: - - name: Install the CI harness interpreter + # Use the hosted tool cache rather than requiring live Ubuntu mirrors. + - uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0 + with: + python-version: '3.12.16' + - name: Verify the CI harness interpreter run: | - apt-get update - apt-get install --yes --no-install-recommends python3 python3 --version - dpkg-query --show python3 python3-minimal + python3 -c 'import ctypes, hashlib, json, sqlite3, ssl, subprocess, tarfile; print("Python runtime imports passed")' - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6 with: persist-credentials: false diff --git a/.github/workflows/native.yml b/.github/workflows/native.yml index efed818..b5d549a 100644 --- a/.github/workflows/native.yml +++ b/.github/workflows/native.yml @@ -13,11 +13,22 @@ jobs: qualification: name: Native execution / ${{ matrix.lane }} runs-on: xcode-27 - timeout-minutes: 60 + timeout-minutes: ${{ matrix.timeout_minutes }} strategy: fail-fast: false matrix: lane: [native, safety, docs, archive, composition] + include: + - lane: native + timeout_minutes: 90 + - lane: archive + timeout_minutes: 90 + - lane: safety + timeout_minutes: 60 + - lane: docs + timeout_minutes: 60 + - lane: composition + timeout_minutes: 60 env: DEVELOPER_DIR: /Applications/Xcode_27.2.app/Contents/Developer PYTHONDONTWRITEBYTECODE: '1' diff --git a/Documentation/Qualification/MaintenanceCI.md b/Documentation/Qualification/MaintenanceCI.md index 9058f8c..db556dd 100644 --- a/Documentation/Qualification/MaintenanceCI.md +++ b/Documentation/Qualification/MaintenanceCI.md @@ -20,8 +20,9 @@ development website. A skipped Pages publication on a maintenance branch is expected. Required product qualification must still execute and pass. Composition has a separate execution matrix lane on macOS and on each Linux -architecture. The native, safety, docs, archive and composition commands retain -their existing 60-minute execution limits; no command or fixture is omitted. +architecture. Native and archive jobs have 90-minute limits; safety, docs, +composition and Linux jobs retain their 60-minute limits. No command or fixture +is omitted. The existing `Native / ...` and `Linux / ...` check names are final gates over their complete workflow execution matrix. They run even after a dependency fails and accept only its `success` result. Failure, cancellation, a skipped execution @@ -58,6 +59,28 @@ measurements as unavailable rather than assigning inferred values. ## Retain build incidents +On 2026-11-11 Linux jobs on both hosted architectures failed before source +checkout because Ubuntu mirror names did not resolve; an unchanged-source retry +failed the same way. A separate diagnostic observed the same resolution failure +on the hosted runners and in the pinned Swift container, while github.com +resolved. The [diagnostic](https://github.com/ThorFuchs/Swift-JSON/actions/runs/43060752165) +successfully set up CPython 3.12.16 and imported the required standard-library +modules in that container on each architecture. The Linux workflow uses the +pinned setup action and exact interpreter version, preserving the Swift image, +execution lanes and fail-closed gates. Setup and the full Linux runs must still +pass for each actual source revision; this diagnostic is not a Linux test pass. + +The same day's Git-free native reproduction exceeded its former 3,300-second limit, +and the separate native job completed with almost no time left in its 60-minute +job. The native and archive job limits are now 90 minutes; the nested native +replay has 5,000 seconds and the outer archive command 5,200 seconds, leaving +time for evidence and artifact upload. +Cleanup then reported a directory-not-empty error while a child build was still +running. The reproduction now stops its ordinary process group and records the +timeout and partial command evidence. The complete reproduction requirement +remains in force; this repair is not an +archive qualification pass. + One Linux Swift 6.4 build-planning SIGSEGV was observed in [the original job](https://github.com/ThorFuchs/Swift-JSON/actions/runs/39039959928/job/117417228489). The complete unchanged normal and composition scope subsequently passed in diff --git a/Scripts/ci.py b/Scripts/ci.py index b939bc7..e03c7ab 100644 --- a/Scripts/ci.py +++ b/Scripts/ci.py @@ -14,6 +14,7 @@ from test_discovery import DISCOVERY, ROOT_COUNTS, SHARED_COUNTS, PARAMETER_INVOCATIONS, check_restored ROOT = pathlib.Path(__file__).resolve().parents[1] +ARCHIVE_COMMAND_TIMEOUT_SECONDS = 5200 SHARED_TESTS = 'independentCodecFacadesAndExactValuesCanBeSharedAcrossTasks|concurrentSchemaEvaluationsHaveExclusiveDynamicRegexAndAnnotationState|sharedRegexProgramHasExclusiveConcurrentSearchState|immutableIndexedObjectCanBeSharedAcrossTasks|qaSharedPayloadAndRootHaveIndependentConcurrentReadScopes|sha256InputCapacityAndConcurrentInvocationsRemainIndependent|sharedFormattedHTMLRendererHasIndependentConcurrentInvocations|sharedAnnotatedDocumentRendererHasIndependentConcurrentInvocations|sharedExportPreparationsHaveIndependentConcurrentState|applePDFSimultaneousJobsHaveIndependentStateAndCancellation|sharedFilterPlanHasIndependentConcurrentInvocations|structuredSharedRendererPlansHaveInvocationOwnedState|sharedProviderBridgeHasIndependentConcurrentInvocations|e2SharedBridgeInputsHaveInvocationOwnedState|e2SharedCompiledPlanFacadeHasIndependentInvocationState' SHARED_TESTS += '|compositionIndependentScopesCanBeSharedAcrossTasks' SHARED_TESTS += '|qaStreaming|qaE2E(SharedPlan|RootImport|NDJSONImport|AwaitedSink|ExactWorkflow)' @@ -189,6 +190,7 @@ def portable(values): ['python3', '-B', 'Scripts/qualify_navigation.py', '--output', str(output / 'consumer')]] if lane == 'archive': return [['python3', '-B', 'Scripts/public_check.py'], + ['python3', '-B', 'Scripts/test_native_reproduction_timeout.py'], ['python3', '-B', 'Scripts/qualify_native_reproduction.py', '--output', str(output / 'reproduction')]] if lane in ('coverage', 'linux-coverage'): return [['python3', '-B', 'Scripts/test_qualification_harness.py'], @@ -579,7 +581,7 @@ def save(): log_path = output / ('command-%02d.log' % index) with log_path.open('w') as stream: try: - result = subprocess.run(command, cwd=ROOT, stdout=stream, stderr=subprocess.STDOUT, timeout=21600 if args.lane in ('wasm', 'wasm-qa') else 3500 if args.lane == 'archive' else 1800) + result = subprocess.run(command, cwd=ROOT, stdout=stream, stderr=subprocess.STDOUT, timeout=21600 if args.lane in ('wasm', 'wasm-qa') else ARCHIVE_COMMAND_TIMEOUT_SECONDS if args.lane == 'archive' else 1800) code = result.returncode except (OSError, subprocess.TimeoutExpired) as error: stream.write('\n' + str(error) + '\n') diff --git a/Scripts/qualify_native_reproduction.py b/Scripts/qualify_native_reproduction.py index eaff94b..516d525 100644 --- a/Scripts/qualify_native_reproduction.py +++ b/Scripts/qualify_native_reproduction.py @@ -5,6 +5,8 @@ import hashlib import json import pathlib +import os +import signal import shutil import subprocess import sys @@ -14,6 +16,22 @@ from archive_candidate import archive, files, verify ROOT = pathlib.Path(__file__).resolve().parents[1] +NATIVE_TIMEOUT_SECONDS = 5000 + + +def run_native(command, cwd, stream, timeout): + """Stop the native process group on timeout before cleaning its extraction.""" + process = subprocess.Popen(command, cwd=cwd, stdout=stream, + stderr=subprocess.STDOUT, start_new_session=True) + try: + return process.wait(timeout=timeout) + except subprocess.TimeoutExpired: + try: + os.killpg(process.pid, signal.SIGKILL) + except ProcessLookupError: + pass + process.wait() + raise def main(): @@ -56,16 +74,28 @@ def save(): command = [sys.executable, '-B', 'Scripts/ci.py', '--lane', 'native'] log = output / 'native.log' start = time.monotonic() + timed_out = False with log.open('w') as stream: - result = subprocess.run(command, cwd=extracted, stdout=stream, - stderr=subprocess.STDOUT, timeout=3300) - receipt['commands'].append(dict(command=command, exit_code=result.returncode, - seconds=time.monotonic() - start, log=log.name, log_sha256=sha(log))) + try: + code = run_native(command, extracted, stream, timeout=NATIVE_TIMEOUT_SECONDS) + except subprocess.TimeoutExpired: + code = None + timed_out = True + receipt['commands'].append(dict(command=command, exit_code=code, + timed_out=timed_out, seconds=time.monotonic() - start, + log=log.name, log_sha256=sha(log))) + if timed_out: + # Preserve the primary failure even if copying partial evidence + # or removing the temporary extraction subsequently fails. + receipt.update(status='failed', error=f'Git-free native lane exceeded the {NATIVE_TIMEOUT_SECONDS}-second limit') + save() child = extracted / '.build/ci/native' if child.is_dir(): shutil.copytree(child, output / 'native', dirs_exist_ok=True, ignore=shutil.ignore_patterns('ModuleCache', '*.dylib', '*.o', '*.swiftmodule')) - if result.returncode: + if timed_out: + raise ValueError(receipt['error']) + if code: raise ValueError('Git-free native lane failed') native = json.loads((output / 'native/receipt.json').read_text()) if native['status'] != 'passed' or native['git_commit'] is not None or not native['source_inputs_unchanged']: @@ -84,7 +114,10 @@ def save(): receipt['native_receipt_sha256'] = sha(output / 'native/receipt.json') receipt['status'] = 'passed' except (OSError, ValueError, KeyError, subprocess.SubprocessError) as error: - receipt.update(status='failed', error=str(error)) + if 'error' in receipt and receipt['error'] != str(error): + receipt['followup_error'] = str(error) + else: + receipt.update(status='failed', error=str(error)) save() print(json.dumps(receipt, indent=2)) return 0 if receipt['status'] == 'passed' else 1 diff --git a/Scripts/test_native_reproduction_timeout.py b/Scripts/test_native_reproduction_timeout.py new file mode 100644 index 0000000..c4ab47f --- /dev/null +++ b/Scripts/test_native_reproduction_timeout.py @@ -0,0 +1,81 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: Apache-2.0 +"""Exercise Git-free reproduction process completion and timeout handling.""" +import pathlib +import subprocess +import sys +import tempfile +import time +import unittest +from unittest.mock import patch + +import qualify_native_reproduction as reproduction +from qualify_native_reproduction import run_native + + +class NativeReproductionTimeoutTests(unittest.TestCase): + def test_preserves_success_and_failure_exit_codes(self): + with tempfile.TemporaryDirectory() as directory: + root = pathlib.Path(directory) + with (root / 'log').open('w') as stream: + for code in (0, 7): + self.assertEqual(run_native([sys.executable, '-c', f'raise SystemExit({code})'], + root, stream, 5), code) + + def test_timeout_stops_a_child_before_it_writes(self): + with tempfile.TemporaryDirectory() as directory: + root = pathlib.Path(directory) + marker = root / 'late-write' + ready = root / 'child-ready' + child = ('import pathlib,sys,time; pathlib.Path(sys.argv[1]).write_text("ready"); ' + 'time.sleep(2.5); pathlib.Path(sys.argv[2]).write_text("late")') + parent = ('import subprocess,sys,time; ' + 'subprocess.Popen([sys.executable,"-c",sys.argv[1],sys.argv[2],sys.argv[3]]); ' + 'time.sleep(10)') + with (root / 'log').open('w') as stream: + with self.assertRaises(subprocess.TimeoutExpired): + run_native([sys.executable, '-c', parent, child, str(ready), str(marker)], + root, stream, 1) + self.assertTrue(ready.exists(), 'child must start before the timeout') + time.sleep(2.6) + self.assertFalse(marker.exists()) + + def test_timeout_remains_primary_when_partial_evidence_copy_fails(self): + import io + import json + import tarfile + from contextlib import redirect_stdout + + with tempfile.TemporaryDirectory() as directory: + root = pathlib.Path(directory) + data = io.BytesIO() + with tarfile.open(fileobj=data, mode='w:gz') as archive: + member = tarfile.TarInfo('Swift-JSON/input') + member.size = 1 + archive.addfile(member, io.BytesIO(b'x')) + + def make_archive(path, _files): + path.write_bytes(data.getvalue()) + + def timeout(_command, cwd, _stream, timeout): + (cwd / '.build/ci/native').mkdir(parents=True) + raise subprocess.TimeoutExpired('native', timeout) + + with patch.object(reproduction, 'ROOT', root), \ + patch.object(reproduction, 'files', return_value=[]), \ + patch.object(reproduction, 'archive', side_effect=make_archive), \ + patch.object(reproduction, 'verify', return_value=1), \ + patch.object(reproduction, 'run_native', side_effect=timeout), \ + patch.object(reproduction.shutil, 'copytree', side_effect=OSError('copy failed')), \ + patch.object(sys, 'argv', ['reproduction', '--output', 'out']), \ + redirect_stdout(io.StringIO()): + self.assertEqual(reproduction.main(), 1) + receipt = json.loads((root / 'out/reproduction.json').read_text()) + self.assertEqual(receipt['status'], 'failed') + self.assertIn(f'{reproduction.NATIVE_TIMEOUT_SECONDS}-second limit', receipt['error']) + self.assertEqual(receipt['followup_error'], 'copy failed') + self.assertTrue(receipt['commands'][0]['timed_out']) + + +if __name__ == '__main__': + unittest.main(verbosity=2) diff --git a/Scripts/test_qualification_harness.py b/Scripts/test_qualification_harness.py index b41bea0..1046433 100644 --- a/Scripts/test_qualification_harness.py +++ b/Scripts/test_qualification_harness.py @@ -15,7 +15,8 @@ import documentation_catalog from coverage import executable_objects, shared_objects, validate_export, without_schema_objects from test_discovery import DISCOVERY, ROOT_COUNTS, PARAMETER_INVOCATIONS, check_root, check_restored, RESTORED_FUNCTIONS -from ci import check_result, commands, SHARED_TESTS, SHARED_COUNTS +from ci import ARCHIVE_COMMAND_TIMEOUT_SECONDS, check_result, commands, SHARED_TESTS, SHARED_COUNTS +from qualify_native_reproduction import NATIVE_TIMEOUT_SECONDS from p2_acceptance import PUBLIC_FUNCTIONS, PUBLIC_SHARED, check_exact_cases, check_exact_receipt from p2_acceptance import EXPECTED as P2_FUNCTIONS, SHARED as P2_SHARED, BORROW_CHECKS, check_p2_cases, check_borrow_receipt, check_private_receipt from graph_acceptance import EXPECTED as GRAPH_FUNCTIONS, check_graph_cases, check_graph_receipt, check_public_graph_receipt, PUBLIC_CHECKS as GRAPH_PUBLIC_CHECKS @@ -73,7 +74,12 @@ def test_workflow_gates_reject_failed_cancelled_skipped_and_missing_results(self def test_composition_scheduling_preserves_timeouts_pins_artifacts_and_pages_guard(self): for filename in ['native.yml','linux.yml']: text, jobs = self.workflow_jobs(filename) - self.assertIn('timeout-minutes: 60', jobs['qualification']) + if filename == 'linux.yml': + self.assertIn('timeout-minutes: 60', jobs['qualification']) + else: + self.assertIn('timeout-minutes: ${{ matrix.timeout_minutes }}', jobs['qualification']) + for lane, limit in [('native', 90), ('archive', 90), ('safety', 60), ('docs', 60), ('composition', 60)]: + self.assertIn(f'- lane: {lane}\n timeout_minutes: {limit}', jobs['qualification']) self.assertIn('fail-fast: false', jobs['qualification']) self.assertIn('persist-credentials: false', jobs['qualification']) self.assertIn('retention-days: 30', jobs['qualification']) @@ -82,11 +88,16 @@ def test_composition_scheduling_preserves_timeouts_pins_artifacts_and_pages_guar self.assertIn('actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f', text) self.assertIn("branches: [main, 'release/1.6']", text) _, native = self.workflow_jobs('native.yml') + self.assertLess(NATIVE_TIMEOUT_SECONDS, ARCHIVE_COMMAND_TIMEOUT_SECONDS) + self.assertLess(ARCHIVE_COMMAND_TIMEOUT_SECONDS, 90 * 60) self.assertIn("if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'", native['publish']) self.assertIn('needs: [qualification, required]', native['publish']) _, linux = self.workflow_jobs('linux.yml') self.assertNotIn('publish', linux) self.assertIn('swift@sha256:31d14d727f4451f25e29bac9c42563a098c39ac66415e8bad970f48038e38aca', linux['qualification']) + self.assertIn('actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548', linux['qualification']) + self.assertIn("python-version: '3.12.16'", linux['qualification']) + self.assertNotIn('apt-get', linux['qualification']) def test_selection_filter_preserves_exact_identity_and_completion_evidence(self): ids = [n for n in DISCOVERY['transform_function_ids'] if '.selection' in n] From c77c57810b1fa88d24a06ffef54b483ecdcc0ac3 Mon Sep 17 00:00:00 2001 From: Thorsten Fuchs <76904008+ThorFuchs@users.noreply.github.com> Date: Wed, 11 Nov 2026 19:32:19 +0100 Subject: [PATCH 3/3] Restore the DocC exclusion in the CLI source identity Maintainer decision: DocC catalogs (*.docc) stay outside the CLI source identity, so documentation-only edits do not require regenerating it. The harness asserts that a catalog change leaves the identity unchanged while a source change still alters it. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 2 ++ Documentation/CLI.md | 3 ++- Scripts/generate_cli_identity.py | 9 ++++++--- Scripts/test_qualification_harness.py | 2 -- Sources/JSONCLIEngine/CLIBuildIdentity.swift | 4 ++-- 5 files changed, 12 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 74d06b3..3db4883 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,8 @@ the iOS simulator, and builds and runs `Tools/PlatformFloorConsumer`, an external consumer declaring the same minimums. Runtime tests on macOS 15-26 or iOS 18 systems remain outside CI. +- The CLI source identity no longer covers DocC catalogs (`*.docc`), so + documentation-only edits no longer require regenerating it. - Repository housekeeping: superseded remote branches removed; branches without a PR were first preserved as `archive/` tags. diff --git a/Documentation/CLI.md b/Documentation/CLI.md index 9436c4a..35fdf12 100644 --- a/Documentation/CLI.md +++ b/Documentation/CLI.md @@ -70,7 +70,8 @@ swift run swift-json --version --json Human output identifies the source version. JSON adds `revisionKind` with value `source-sha256`; `revision` is `sha256:` plus a lowercase 64-digit digest. This digest hashes the ordered content manifest for `Package.swift` and every file in -`Sources`, excluding only generated `CLIBuildIdentity.swift`. The manifest uses +`Sources`, excluding generated `CLIBuildIdentity.swift` and DocC catalogs +(`*.docc`), which are documentation rather than compiled source. The manifest uses UTF-8 relative paths and SHA-256 file digests. It is a source-content identity, not a Git commit, binary digest, wall-clock build ID or assertion of publication. diff --git a/Scripts/generate_cli_identity.py b/Scripts/generate_cli_identity.py index 54bc83d..04a76ae 100644 --- a/Scripts/generate_cli_identity.py +++ b/Scripts/generate_cli_identity.py @@ -14,7 +14,10 @@ def rendered(root=ROOT): paths = [root / 'Package.swift'] + sorted((root / 'Sources').rglob('*')) records = [] for path in paths: - if not path.is_file() or path.relative_to(root) == GENERATED: + relative = path.relative_to(root) + # DocC catalogs are documentation, not compiled source; editing them does not + # change the executable, so they are outside the source identity. + if not path.is_file() or relative == GENERATED or any(part.endswith('.docc') for part in relative.parts): continue if path.is_symlink(): raise ValueError('Source identity cannot follow symlinks') @@ -22,7 +25,7 @@ def rendered(root=ROOT): value = hashlib.sha256(''.join(records).encode()).hexdigest() return ('// SPDX-License-Identifier: Apache-2.0\n' '// Generated by Scripts/generate_cli_identity.py; excludes this file.\n' - '// SHA-256 of the ordered Package.swift + Sources content manifest, not a Git commit.\n' + '// SHA-256 of the ordered Package.swift + Sources content manifest (DocC catalogs excluded), not a Git commit.\n' 'package enum CLIBuildIdentity {\n' ' package static let revision = "sha256:' + value + '"\n' ' package static let kind = "source-sha256"\n' @@ -41,7 +44,7 @@ def main(): return 1 else: path.write_text(expected) - print('CLI_IDENTITY passed source_manifest=Package.swift+Sources git_required=false') + print('CLI_IDENTITY passed source_manifest=Package.swift+Sources-without-docc git_required=false') return 0 diff --git a/Scripts/test_qualification_harness.py b/Scripts/test_qualification_harness.py index 60a731e..97d2893 100644 --- a/Scripts/test_qualification_harness.py +++ b/Scripts/test_qualification_harness.py @@ -620,8 +620,6 @@ def test_cli_identity_ignores_git_time_and_generated_output_but_detects_source_c self.assertEqual(rendered(self.root), first) catalog = self.root / 'Sources/JSONCLIEngine/Documentation.docc'; catalog.mkdir() (catalog / 'Guide.md').write_text('# Documentation-only change\n') - self.assertNotEqual(rendered(self.root), first) - (catalog / 'Guide.md').unlink() self.assertEqual(rendered(self.root), first) owned.write_text('let version = "1.5.2"\n') self.assertNotEqual(rendered(self.root), first) diff --git a/Sources/JSONCLIEngine/CLIBuildIdentity.swift b/Sources/JSONCLIEngine/CLIBuildIdentity.swift index 0b198c1..d2437cc 100644 --- a/Sources/JSONCLIEngine/CLIBuildIdentity.swift +++ b/Sources/JSONCLIEngine/CLIBuildIdentity.swift @@ -1,7 +1,7 @@ // SPDX-License-Identifier: Apache-2.0 // Generated by Scripts/generate_cli_identity.py; excludes this file. -// SHA-256 of the ordered Package.swift + Sources content manifest, not a Git commit. +// SHA-256 of the ordered Package.swift + Sources content manifest (DocC catalogs excluded), not a Git commit. package enum CLIBuildIdentity { - package static let revision = "sha256:aa26808464399893b8609da161cc55d93a4cc1c24437091570ec4f639beb22d6" + package static let revision = "sha256:3b65f6ca79902befb4c50649094739bf30838631c2f2fbc46515c2c6df64e164" package static let kind = "source-sha256" }