Vendored Dependencies Policy

This project vendors parts of third-party libraries to ensure stability, provenance, and reproducibility of core methods.

SparseSC (Microsoft)

  • Source: https://github.com/microsoft/SparseSC
  • Vendored Path: src/sparsesc/
  • Pinned upstream commit: 3b4d2ebd87b41fc8e0ec3e97fcb2be1b689275c0
  • Status: src/sparsesc/ is a governed integration fork of Microsoft’s SparseSC.
  • Technical provenance: See src/sparsesc/PROVENANCE.md for upstream commit, local modifications, coupling notes, and update procedure.
  • Change Policy: Modifications to src/sparsesc/ must be documented in src/sparsesc/PROVENANCE.md with rationale and verification impact.
  • Tooling: Excluded from formatting, linting, and typing checks (see pyproject.toml).
  • Release certification: GeoSC validates the first-party wrapper boundary around vendored SparseSC through the statistical certification gate in scripts/verify_release_candidate.py. The gate checks adapter/result parity, effect recovery, timing/orientation, artifact schemas, uncertainty and placebo metadata, and related advisory diagnostics. It does not treat passing wrapper tests as proof that a specific campaign satisfies SparseSC’s causal design assumptions.
  • Known cleanup candidate: src/sparsesc/utils/AzureBatch/ remains part of the governed vendored SparseSC fork. Removing or pruning it requires a separate SparseSC provenance-backed phase with documented rationale, verification impact, and an update to src/sparsesc/PROVENANCE.md.

synthdid (if retained)

  • Vendored Path: src/synthdid/
  • Status: Not used by the primary GeoLiftAnalyzer workflow.
  • Recommendation: Either remove it entirely, or expose it behind a stable adapter interface and document its usage with tests.
  • Tooling: Excluded from formatting, linting, and typing checks.

Update Procedure

  1. Keep a file-local provenance record for each vendored dependency.
  2. Verify unit, integration, and performance tests pass after a refresh.
  3. Update pyproject.toml exclusion lists only if vendored paths change.
  4. Document any intentional local modifications in the dependency-specific provenance file.