diff --git a/vault/03-context/index.md b/vault/03-context/index.md index ecc49e0..8bac102 100644 --- a/vault/03-context/index.md +++ b/vault/03-context/index.md @@ -1,7 +1,7 @@ --- type: context-index project: fidelity -updated: 2026-04-16 +updated: 2026-04-17 tags: - context - map @@ -36,6 +36,7 @@ Swift and iOS best-practice context for programming questions: - [ios/index.md](./ios/index.md) - [ios/current-practices.md](./ios/current-practices.md) - [ios/project-swift-guidance.md](./ios/project-swift-guidance.md) +- [ios/cocoapods-dependency-management.md](./ios/cocoapods-dependency-management.md) ### `workstreams/` diff --git a/vault/03-context/ios/cocoapods-dependency-management.md b/vault/03-context/ios/cocoapods-dependency-management.md new file mode 100644 index 0000000..6e0ec61 --- /dev/null +++ b/vault/03-context/ios/cocoapods-dependency-management.md @@ -0,0 +1,78 @@ +--- +type: guidance +project: fidelity +status: active +updated: 2026-04-17 +tags: + - ios + - cocoapods + - dependencies + - fidelity +--- +# CocoaPods Dependency Management + +## Goal + +Help the agent reason correctly about CocoaPods behavior, private podspec repos, and release propagation in the Fidelity iOS ecosystem. + +--- + +## Why This Matters Here + +- CocoaPods is a core part of how XFlowSDK changes reach XFlowViewMaker, FTFrameworks, and Fid4. +- Many apparent SDK or consumer issues are actually dependency-resolution or published-podspec issues. +- The workspace should treat CocoaPods knowledge as part of normal investigation and release reasoning, not as an edge case. + +--- + +## Fidelity-Specific Context + +- XFlowSDK releases publish artifacts and podspec updates that downstream consumers adopt through CocoaPods. +- XFlowViewMaker, FTAccountOpen, FTTransfer, and Fid4 propagation all depend on correct podspec and resolver behavior. +- The effective dependency constraint can come from the published podspec repo layer, not only from the source repo that developers inspect first. +- Fid4 currently does not keep `Podfile.lock` in Git, which weakens reproducibility and makes published podspec changes more operationally significant. + +--- + +## Agent Rules + +- When a newly published dependency does not resolve in Fid4, check CocoaPods resolution before assuming the code change failed. +- Distinguish these layers: + - source repo podspec or helper code + - published private podspec repo + - consumer `Podfile` + - local/pipeline lockfile state +- Do not assume FTFrameworks source tells the whole truth about the active dependency graph. +- Treat private podspec repo edits as high-signal release-path behavior that may explain why local or pipeline resolution differs from expectations. +- When giving advice, separate: + - what fixed the immediate unblock + - what is healthy long-term dependency management + +--- + +## CocoaPods Best-Practice Anchors + +- CocoaPods podspecs are expected to declare dependency requirements explicitly. +- CocoaPods documentation recommends the optimistic operator `~>` because it provides version control without being overly restrictive. +- Overly restrictive dependency requirements can block compatibility. +- Removing dependency constraints entirely can weaken compatibility guarantees and make transitive resolution less predictable. +- `pod install` is the normal command after dependency-definition changes; `pod update` is for intentionally updating pod versions. +- `Podfile.lock` is important for reproducible installs and should normally be committed. + +--- + +## Current Project Caution + +- In this project, removing the XFlowViewMaker version reference from published `FTAccountOpen` and `FTTransfer` podspecs unblocked Fid4 resolution. +- That should be understood as the current operational fix, not automatically as the ideal dependency-management pattern. +- Because `Podfile.lock` is not committed in Fid4, broad podspec-repo edits can silently change future resolutions more than they should in a healthier CocoaPods setup. + +--- + +## What Good Answers Should Include + +- Whether the issue is in source code, published specs, or consumer resolution +- Whether `pod install`, `pod install --repo-update`, or `pod update` is the appropriate command for the stated goal +- Whether the current fix improves compatibility or only removes guardrails +- Whether the result is reproducible or vulnerable to future resolver drift +- Whether the advice is a short-term unblock or a durable recommendation diff --git a/vault/03-context/ios/index.md b/vault/03-context/ios/index.md index 7b4ba87..7428d3b 100644 --- a/vault/03-context/ios/index.md +++ b/vault/03-context/ios/index.md @@ -2,7 +2,7 @@ type: guidance-index project: fidelity status: active -updated: 2026-04-16 +updated: 2026-04-17 tags: - ios - fidelity @@ -23,10 +23,14 @@ Help the agent answer Swift and iOS programming questions with current best prac - [project-swift-guidance.md](./project-swift-guidance.md) Fidelity-specific guidance for applying Swift/iOS advice in this workspace. +- [cocoapods-dependency-management.md](./cocoapods-dependency-management.md) + CocoaPods, private podspec repo, and dependency-resolution guidance for Fidelity release and consumer integration work. + --- ## Usage - Use these files before answering Swift, SwiftUI, iOS architecture, testing, concurrency, or debugging questions. +- Use the CocoaPods guidance whenever the question touches release propagation, podspecs, dependency conflicts, Fid4 resolution, or FTFrameworks consumer updates. - When a recommendation depends on current Apple APIs, prefer official Apple or Swift documentation before making strong claims. - Keep project constraints visible: XFlow is backend-driven, Fid4 is consumer validation, and REST/GraphQL migration constraints may affect architecture. diff --git a/vault/03-context/ios/project-swift-guidance.md b/vault/03-context/ios/project-swift-guidance.md index 7086ce3..f95a8b5 100644 --- a/vault/03-context/ios/project-swift-guidance.md +++ b/vault/03-context/ios/project-swift-guidance.md @@ -2,7 +2,7 @@ type: guidance project: fidelity status: active -updated: 2026-04-16 +updated: 2026-04-17 tags: - ios - fidelity @@ -20,6 +20,7 @@ Apply Swift/iOS advice in a way that fits Fidelity's XFlow, Fid4, XFlowViewMaker - XFlow is backend-driven; UI behavior may be service/configuration driven, not purely local Swift code. - Fid4 is the real consumer validation target for many issues. - XFlowViewMaker and FTFrameworks can affect whether a fix is visible in Fid4. +- CocoaPods and private podspec-repo behavior are part of the real integration surface, not just build tooling details. - REST migration constraints still matter; do not assume REST is active by default. - Some work happens behind feature flags, especially risky consumer-impact changes. @@ -43,4 +44,5 @@ Apply Swift/iOS advice in a way that fits Fidelity's XFlow, Fid4, XFlowViewMaker - If the user asks a general Swift question, answer generally but include a Fidelity/XFlow note when relevant. - If the user asks about a code change, separate modern best practice from what is safe for the current project. - If codebase constraints are unknown, say what must be confirmed: deployment target, Xcode version, module ownership, feature flag path, and consumer validation path. +- If the work touches dependency propagation, published specs, or consumer upgrade behavior, explicitly include CocoaPods and podspec-repo reasoning instead of treating them as secondary operational noise. - For manager-ready explanations, connect the technical recommendation to scope, risk, and validation. diff --git a/vault/03-context/workstreams/consumer-integration.md b/vault/03-context/workstreams/consumer-integration.md index 0d832d7..acf6dfe 100644 --- a/vault/03-context/workstreams/consumer-integration.md +++ b/vault/03-context/workstreams/consumer-integration.md @@ -95,6 +95,10 @@ Capture the durable release and validation path between XFlow changes and real c - For the current XFlowViewMaker propagation issue, the practical fix was made in the podspec repo by removing the XFlowViewMaker version reference from both the latest `FTAccountOpen` and `FTTransfer` podspecs. - After that podspec-repo PR was merged, `pod install --repo-update` in Fid4 resolved successfully because those podspecs no longer constrained the XFlowViewMaker version. - `FTAccountOpen` and `FTTransfer` do not appear to hold a direct XFlowViewMaker version reference in their checked FTFrameworks source podspec files; the effective resolution is managed through the published podspec layer and `ftAdapter` behavior. +- This appears to be a risky workaround rather than a healthy long-term dependency-management pattern. +- CocoaPods documentation recommends explicit dependency requirements in podspecs and specifically recommends the optimistic operator `~>` because it gives version control without being overly restrictive. +- Removing version constraints entirely from published intermediate podspecs weakens compatibility guarantees, makes transitive resolution less predictable, and increases the chance that consumers pick up unvalidated downstream versions. +- That risk is even higher in this workspace because Fid4 does not keep `Podfile.lock` in Git, so published podspec changes can alter future resolutions without a strong repository-level lockfile trail. ---