docs(sdd-119)+feat(macos): consolidate deployment-target SoT (SDD-119 amendment v0.9.17)

Resolve the macOS half of the SDD-119 item 3 single-source-of-truth follow-up. The chanora_bridge cdylib macOS deployment-target floor ('10.15') was previously hard-coded at 7 sites across Podfile and chanora_bridge.podspec; this commit collapses them to a single Ruby constant declaration in a new SoT file. Selected Option B (Ruby constant) over Option A (.xcconfig — rejected because the podspec prepare_command runs before any xcconfig is applied) and Option C (versioned text file — rejected as overkill given both consumers are already Ruby). Realizes SAD-087(a)'s 'single macOS build-configuration location' mandate. Out of scope: the pbxproj 'MACOSX_DEPLOYMENT_TARGET = 10.15' lines (565/666/717) belong to the PBXProject default config and are independently overridden to '11.0' at the Runner PBXNativeTarget level; they are the Runner app's floor, not the bridge cdylib's floor. The iOS half (IPHONEOS_DEPLOYMENT_TARGET=13.0) remains an open follow-up. Files: new apps/chanora_flutter/macos/macos_deployment_target.rb (MACOS_BRIDGE_DEPLOYMENT_TARGET = '10.15'.freeze); Podfile + chanora_bridge.podspec require_relative the constant and consume it at 7 sites; docs/architecture/sdd.md SDD-119 item 3 rewritten + Notes bullet updated + v0.9.17 changelog entry.
2026-05-18 14:39:14 +08:00
parent 92087d066a
commit a77a9b2ef2
4 changed files with 40 additions and 10 deletions
@@ -1,4 +1,5 @@
-platform :osx, '10.15'
+require_relative 'macos_deployment_target'
+platform :osx, MACOS_BRIDGE_DEPLOYMENT_TARGET

 # CocoaPods analytics sends network stats synchronously affecting flutter build latency.
 ENV['COCOAPODS_DISABLE_STATS'] = 'true'
@@ -24,6 +24,8 @@
 # prepare_command runs with PWD = the directory of this file, so all
 # paths are relative to apps/chanora_flutter/macos/.

+require_relative 'macos_deployment_target'
+
 Pod::Spec.new do |s|
  s.name             = 'chanora_bridge'
  s.version          = '1.0.0'
@@ -36,7 +38,7 @@ Pod::Spec.new do |s|
  s.license          = { :type => 'Apache-2.0 OR MIT', :text => 'See LICENSE-APACHE / LICENSE-MIT at the repo root' }
  s.author           = { 'EdisonJwa' => 'me@edison.network' }
  s.source           = { :path => '.' }
-  s.platform         = :osx, '10.15'
+  s.platform         = :osx, MACOS_BRIDGE_DEPLOYMENT_TARGET

  # Build the Rust bridge on `pod install`. The script runs under
  # bash; we use `set -e` so any failure (cargo missing, target not
@@ -51,7 +53,7 @@ Pod::Spec.new do |s|
    echo "[chanora_bridge.podspec] cargo build aarch64-apple-darwin"
    cd "$REPO_ROOT"
    PATH="$HOME/.cargo/bin:$PATH" \\
-      MACOSX_DEPLOYMENT_TARGET=10.15 \\
+      MACOSX_DEPLOYMENT_TARGET=#{MACOS_BRIDGE_DEPLOYMENT_TARGET} \\
      CMAKE_POLICY_VERSION_MINIMUM=3.5 \\
      LIBOPUS_STATIC=1 \\
      LIBOPUS_NO_PKG=1 \\
@@ -59,7 +61,7 @@ Pod::Spec.new do |s|

    echo "[chanora_bridge.podspec] cargo build x86_64-apple-darwin"
    PATH="$HOME/.cargo/bin:$PATH" \\
-      MACOSX_DEPLOYMENT_TARGET=10.15 \\
+      MACOSX_DEPLOYMENT_TARGET=#{MACOS_BRIDGE_DEPLOYMENT_TARGET} \\
      CMAKE_POLICY_VERSION_MINIMUM=3.5 \\
      LIBOPUS_STATIC=1 \\
      LIBOPUS_NO_PKG=1 \\
@@ -103,7 +105,7 @@ Pod::Spec.new do |s|
  <key>CFBundleShortVersionString</key><string>1.0.0</string>
  <key>CFBundleVersion</key><string>1</string>
  <key>CFBundleSupportedPlatforms</key><array><string>MacOSX</string></array>
-  <key>MinimumOSVersion</key><string>10.15</string>
+  <key>MinimumOSVersion</key><string>#{MACOS_BRIDGE_DEPLOYMENT_TARGET}</string>
 </dict>
 </plist>
 PLIST
@@ -140,7 +142,7 @@ PLIST
      echo "[chanora_bridge script_phase] cargo build aarch64-apple-darwin"
      cd "$REPO_ROOT"
      PATH="$HOME/.cargo/bin:$PATH" \
-        MACOSX_DEPLOYMENT_TARGET=10.15 \
+        MACOSX_DEPLOYMENT_TARGET=#{MACOS_BRIDGE_DEPLOYMENT_TARGET} \
        CMAKE_POLICY_VERSION_MINIMUM=3.5 \
        LIBOPUS_STATIC=1 \
        LIBOPUS_NO_PKG=1 \
@@ -148,7 +150,7 @@ PLIST

      echo "[chanora_bridge script_phase] cargo build x86_64-apple-darwin"
      PATH="$HOME/.cargo/bin:$PATH" \
-        MACOSX_DEPLOYMENT_TARGET=10.15 \
+        MACOSX_DEPLOYMENT_TARGET=#{MACOS_BRIDGE_DEPLOYMENT_TARGET} \
        CMAKE_POLICY_VERSION_MINIMUM=3.5 \
        LIBOPUS_STATIC=1 \
        LIBOPUS_NO_PKG=1 \
@@ -188,7 +190,7 @@ PLIST
  <key>CFBundleShortVersionString</key><string>1.0.0</string>
  <key>CFBundleVersion</key><string>1</string>
  <key>CFBundleSupportedPlatforms</key><array><string>MacOSX</string></array>
-  <key>MinimumOSVersion</key><string>10.15</string>
+  <key>MinimumOSVersion</key><string>#{MACOS_BRIDGE_DEPLOYMENT_TARGET}</string>
 </dict>
 </plist>
 PLIST
@@ -0,0 +1,21 @@
+# Single source of truth for the macOS deployment-target floor consumed by the
+# chanora_bridge Rust cdylib build (SAD-087(a), SDD-119 v0.9.17 amendment).
+#
+# This value is the macOS SDK floor against which `libchanora_bridge.dylib` is
+# compiled — it is NOT the Flutter Runner app's deployment target (which lives
+# in Runner.xcodeproj/project.pbxproj at the PBXNativeTarget level and is
+# currently `11.0`). The bridge floor is intentionally broader (`10.15`) so the
+# cdylib symbols remain link-compatible with any consumer >= 10.15; the Runner
+# app's own minimum is independently set at the Xcode-target layer.
+#
+# Consumers:
+#   - apps/chanora_flutter/macos/Podfile (`platform :osx, ...`)
+#   - apps/chanora_flutter/macos/chanora_bridge.podspec
+#       (`s.platform`, the prepare_command / script_phase
+#        `MACOSX_DEPLOYMENT_TARGET=...` env exports, and the embedded
+#        framework Info.plist `MinimumOSVersion`)
+#
+# To bump the floor, edit ONLY this file. Do not introduce any other literal
+# occurrence of the floor string in this directory.
+
+MACOS_BRIDGE_DEPLOYMENT_TARGET = '10.15'.freeze
@@ -1682,7 +1682,7 @@ Implementation requirements (back-fill of existing podspec automation):
   - CocoaPods `vendored_frameworks` integration is identical to iOS in mechanism.
   - Caching: cargo incremental + per-platform timestamp guard inside the `script_phase`, identical to iOS.

-3. Deployment-target source-of-truth (open improvement, not blocking this back-fill): `IPHONEOS_DEPLOYMENT_TARGET=13.0` is currently hard-coded in the iOS podspec; `MACOSX_DEPLOYMENT_TARGET=10.15` is currently hard-coded in the macOS podspec. There is no shared properties file that both podspecs read. A future SDD revision may move both to a single shared config artefact (analogous to how SDD-073 / SDD-118 item 2 isolate the Android `minSdk` to one Gradle property). Flagged here; NOT required to fix as part of this back-fill.
+3. Deployment-target source-of-truth — RESOLVED for macOS (v0.9.17 amendment): the macOS bridge deployment-target floor (`10.15`) is now sourced from a single Ruby constant `MACOS_BRIDGE_DEPLOYMENT_TARGET` declared in `apps/chanora_flutter/macos/macos_deployment_target.rb` and `require_relative`-loaded by both `apps/chanora_flutter/macos/Podfile` (consumed as the argument to `platform :osx, ...`) and `apps/chanora_flutter/macos/chanora_bridge.podspec` (consumed by `s.platform :osx, ...`, by the four `MACOSX_DEPLOYMENT_TARGET=...` env exports inside the `prepare_command` and `script_phase` heredocs via Ruby `#{...}` interpolation, and by the two embedded framework `Info.plist` `<key>MinimumOSVersion</key>` entries that are emitted inside the same heredocs). This realizes SAD-087(a)'s "single macOS build-configuration location" mandate as Option B (Ruby constant, scoped narrowly to the chanora_bridge Rust-cdylib baseline), selected over Option A (`.xcconfig`) because the bridge baseline is consumed by the podspec's `prepare_command` BEFORE any xcconfig is applied — a Ruby-evaluation-time constant is the only mechanism that reaches every consumer site without indirection — and over Option C (versioned text file) on the grounds that the bridge consumers are all already Ruby files, so a Ruby constant adds zero new file-format burden. The pbxproj `MACOSX_DEPLOYMENT_TARGET = 10.15` occurrences at `Runner.xcodeproj/project.pbxproj` lines 565, 666, 717 are explicitly OUT OF SCOPE for this SoT: those three lines belong to the PBXProject "Runner" build-configuration list (i.e. the project-default config that Flutter's `flutter create` template emits) and are independently overridden to `11.0` at the Runner PBXNativeTarget level (project.pbxproj lines 756, 782, 614) — they are the Runner app's project-default floor, not the bridge cdylib's floor; the matching `10.15` value is coincidental and the two values can legitimately diverge in the future (e.g., raising the bridge to `11.0` while leaving the Runner app's project-default at `10.15`, or vice versa). To bump the bridge floor, edit ONLY `macos_deployment_target.rb`; do not introduce any other literal occurrence of the floor string under `apps/chanora_flutter/macos/`. The iOS half of this follow-up (`IPHONEOS_DEPLOYMENT_TARGET=13.0` hard-coded in the iOS podspec) is intentionally NOT addressed by this amendment — the iOS podspec is a separate Ruby file with no Podfile-shared baseline (the iOS Podfile uses a Flutter-template-generated `platform :ios, ...` line that already lives in its own configuration scope) and a parallel SoT consolidation for iOS is recorded as a follow-up SDD revision.

 4. iOS simulator slice — RESOLVED (decision: Option α, drop the misleading comment): P0 scope intentionally excludes `aarch64-apple-ios-sim`; the iOS podspec comment at `apps/chanora_flutter/ios/chanora_bridge.podspec:9-10` referencing simulator support is to be removed in a follow-up commit so the in-file docstring matches the actual cargo invocation (which builds only `aarch64-apple-ios`). Rationale for choosing Option α over adding the sim slice: P0 minimalism — simulator support is a P1 concern; expanding the iOS build matrix at P0 expands scope without serving a P0 verification need. Implication for downstream: building the Runner for an iOS simulator currently relies on Xcode's own handling of an arm64-device-only framework on Apple-silicon hosts; Intel-host iOS simulator builds are not supported by this automation as written. A future SDD revision (P1) may add the simulator slice; until then, the podspec comment shall be dropped to eliminate the doc-drift defect.

@@ -1700,7 +1700,7 @@ Implementation requirements (back-fill of existing podspec automation):

 Notes:

- This is a back-fill SDD. No new implementation work is created by SDD-119; the code already exists and ships. A builder agent does NOT need to act on SDD-119. The doc-drift defect in item 4 and the deployment-target single-source-of-truth improvement in item 3 are recorded as open follow-ups and are not in scope for this unit.
+- This is a back-fill SDD. No new implementation work is created by SDD-119; the code already exists and ships. A builder agent does NOT need to act on SDD-119. The doc-drift defect in item 4 is RESOLVED (v0.9.13). The macOS deployment-target single-source-of-truth follow-up in item 3 is RESOLVED for macOS (v0.9.17); the iOS half remains an open follow-up for a future SDD revision.
 - SAD-side anchoring of the build-automation pattern at the architectural layer is NOT performed by this SDD unit; a software-architect dispatch is required if the orchestrator wants a SAD-layer build-automation item.

 **SDD-120 — Realtime audio benchmark harness and advisory CI infrastructure**
@@ -1925,3 +1925,9 @@ Notes:
 | Version | Date | Description |
 | --- | --- | --- |
 | 0.9.16 | 2026-05-18 | SDD-120 amendment: clarify the post-processor binary placement at `crates/chanora_audio/examples/` rather than `benches/` or `src/bin/`. Rationale: Cargo's dependency resolver only routes `[dev-dependencies]` to `[[test]]`, `[[bench]]`, and `[[example]]` targets; `src/bin/` placement would have forced `serde_json` and other dev-only crates into production builds. Reflects commit 3a7750a discovery. No semantic change to SDD-120 — same harness, same metrics, same workflows, same out-of-scope deferrals; only the path conventions and invocation flags (`--example` not `--bin`) corrected. Edits scoped to SDD-120: (1) "Allocated to" line gains `crates/chanora_audio/examples/` alongside `benches/`; (2) "Software units" list relocates `emit_baseline.rs` and `compare_baseline.rs` from `benches/` to `examples/`; (3) §1 item 4 reworded from `[[bin]]` entries pointing into `benches/` to `[[example]]` entries (auto-discovered under `examples/`) with `cargo run --example` invocation pattern; (4) §2 gains a new item 5 stating the `examples/` rationale and the dev-only isolation property; (5) §5 item 1 path updated and invocation-flag note added; (6) §5 item 4 rationale clause updated to reference the `[dev-dependencies]`-to-examples routing; (7) §6 step 6 and step 8 invocation flags changed `--bin` → `--example`; (8) §7 step 5 invocation flag changed `--bin` → `--example`; (9) §10 item 1 release-artifact-isolation bullet extended with an explicit note that the `examples/` placement is the Cargo-design mechanism enforcing the exclusion of `[dev-dependencies]` (including `serde_json`, `criterion`, `dhat`) from `cargo build --release` and from `flutter build apk/aab/ipa --release`. §11 verification matrix unchanged. Coverage matrix row for SAD-088..SAD-091 unchanged. The SDD-120 spec is otherwise byte-identical to v0.9.15. |
+
+## Baseline Candidate 0.9.17 Update
+
+| Version | Date | Description |
+| --- | --- | --- |
+| 0.9.17 | 2026-05-18 | SDD-119 amendment: macOS deployment-target single-source-of-truth (open follow-up flagged at SDD-119 item 3 since v0.9.10 and explicitly deferred at v0.9.13) RESOLVED for the macOS half. Selected Option B (Ruby constant) over Option A (`.xcconfig`) and Option C (versioned text file); rationale recorded inline at the rewritten item 3. New SoT file `apps/chanora_flutter/macos/macos_deployment_target.rb` declares a single frozen Ruby constant `MACOS_BRIDGE_DEPLOYMENT_TARGET = '10.15'.freeze`; `apps/chanora_flutter/macos/Podfile` and `apps/chanora_flutter/macos/chanora_bridge.podspec` `require_relative` the file and consume the constant at seven previously-literal sites (1 Podfile `platform :osx, ...`; 1 podspec `s.platform :osx, ...`; 4 podspec `MACOSX_DEPLOYMENT_TARGET=...` env exports inside the `prepare_command` and `script_phase` shell heredocs, reached via outer-Ruby-heredoc `#{...}` interpolation; 2 podspec embedded-framework `Info.plist` `<key>MinimumOSVersion</key>` entries, reached the same way). The pbxproj `MACOSX_DEPLOYMENT_TARGET = 10.15` occurrences at `Runner.xcodeproj/project.pbxproj` lines 565 / 666 / 717 are explicitly OUT OF SCOPE for this SoT and were NOT touched: those three lines belong to the PBXProject "Runner" build-configuration list (project-default config emitted by Flutter's template) and are independently overridden to `11.0` at the Runner PBXNativeTarget level — they are the Runner app's project-default floor, not the bridge cdylib's floor, and the matching value is coincidental and intentionally allowed to diverge in the future. The iOS half of the SoT follow-up (`IPHONEOS_DEPLOYMENT_TARGET=13.0` hard-coded in the iOS podspec) remains an open follow-up and is NOT addressed by this amendment — the iOS Podfile / podspec pair sits in a separate directory under a parallel Ruby scope and warrants its own future revision. SDD-119 item 3 fully rewritten in place (no longer flagged as open follow-up — now records the Option-B realization, the consumer-site enumeration, the option-rejection rationale, and the explicit OUT-OF-SCOPE note for the pbxproj project-default lines). SDD-119 "Notes" bullet at line 1703 updated to reflect that item 3 is RESOLVED for macOS while preserving the iOS-half open-follow-up status. Source SAD: SAD-087(a) (which already named the podspec as the "single macOS build-configuration location") — this amendment realizes that mandate by collapsing the seven intra-cluster literal occurrences to one. Files modified: `apps/chanora_flutter/macos/macos_deployment_target.rb` (new, ~22 lines including documentation header), `apps/chanora_flutter/macos/Podfile` (+1 line `require_relative`, 1 line edited), `apps/chanora_flutter/macos/chanora_bridge.podspec` (1 line `require_relative` insertion + 7 literal-to-interpolation edits), `docs/architecture/sdd.md` (this entry + item-3 rewrite + Notes-bullet edit). No behavioural design content changed beyond consolidating an already-implemented value to a single declaration site. The pre-staged `apps/chanora_flutter/macos/Frameworks/chanora_bridge.framework/Versions/A/Resources/Info.plist` artifact still contains the literal `10.15` value but is regenerated on every `pod install` / Xcode build by the podspec's `prepare_command` / `script_phase` from the new SoT, so it will refresh automatically on the next macOS build. Strict layered sourcing preserved (`SDD -> SAD` only). Ruby syntax of the modified files NOT executable-verified on this host (no `ruby` available in the build container); static review confirmed (a) the `require_relative 'macos_deployment_target'` filename is correct (the new file is named `macos_deployment_target.rb` and `require_relative` strips the `.rb` extension), (b) the constant is referenced after the require in every consumer, (c) the outer Ruby heredocs (`<<-SCRIPT`, unquoted delimiter) support `#{...}` interpolation, (d) the inner shell `<<PLIST` heredoc inside those Ruby heredocs is interpolated at outer-Ruby-heredoc evaluation time before the shell ever sees the string, so the embedded `Info.plist` `MinimumOSVersion` interpolations are well-formed. Recommended next step: orchestrator push, then on next macOS developer machine `pod install` to refresh the staged framework Info.plist. |