[truealpha-bt] Select Qlib for factor and backtest execution

[wangzitian0]

Summary

• select Qlib as the version-pinned factor-expression and backtest engine
• keep PIT selection, provenance, confidence, Decimal monetary semantics, membership, lineage, and the corporate-action event clock under TrueAlpha-owned contracts and libs/factors adapters
• bind Gate 1 Local/Staging evidence to the same Qlib build, adapter, operator registry, strategy, and snapshots
• rebind the structurally valid but externally blocked Gate 0 candidate to current main without changing its payload, status, or blockers

Why

The architecture defined deterministic replay semantics but had not selected the implementation engine. Qlib supplies serializable factor expressions and a research backtest path while the adapter boundary prevents it from becoming a second data, vintage, or computation authority.

PRs #194 and #195 provide accepted E0/E1 safe-expression evidence for pinned Qlib 0.9.7. They do not replace this authoritative architecture decision and do not implement or accept the complete #26 provider/executor replay.

Validation

Passed on rebased head 71e5a0fec60944d2d979908d9f8a6699016b585d:

• make gate0-candidate-check
• make issue-graph-check
• governance regression tests: 102 passed
• isolated Qlib contract tests: 33 passed
• targeted Ruff and format checks
• exact-head offline graph, 65-issue live GitHub parity, and pull-request authorization

The previous Delivery Governance / validate failure was caused by the old workflow treating a structurally valid blocked Gate candidate as requiring acceptance. #199 corrected that merge-authorization defect; no bypass flag is used.

Evidence ceiling

This PR records an architecture decision only. It does not implement replay, accept Gate 0 or Gate 1, approve a stable handoff, or claim Production readiness. Issue #26 remains open for the provider/executor, PIT replay, mart/report, holdout, and exact capture-to-decision evidence.

Gate manifest: governance/gate0/manifest-v4.json

Manifest SHA-256: 3f7e6543c06dac72d8487cd24174f1d15b70b7aebdcd4da1bafce66cff1e9ff1

Refs #26

[wangzitian0]

Architecture review outcome: the high-level boundary in this PR is sound and should remain in init.md: Qlib is an execution engine behind libs/factors, never the PIT/provenance/Decimal authority.

The implementation obligations were underspecified in the issue graph, so I updated #26 and recast #181/S7 accordingly:

• initial engine binding is pyqlib==0.9.7, with the actual installed artifact hash pinned by the lock and run evidence;
• Qlib is isolated in the workspace-excluded libs/factors/qlib-runtime project with its own lock because a workspace extra still downgraded root pandas and polluted the root lock;
• the adapter must reject Decimal-to-float collisions/order changes;
• Qlib's stateful TopkDropoutStrategy(topk, n_drop) is not treated as equivalent to the current full-rebalance top-N golden;
• an independent Decimal oracle, not shared production code, is the parity authority.

No additional init.md change is required for those implementation details. #26 now owns them; #25 remains the Decimal valuation-signal owner.

[Copilot]

Pull request overview

This PR updates the repository’s authoritative architecture documentation to explicitly select Qlib as the factor-expression/backtest engine (while preserving TrueAlpha-owned PIT/provenance/confidence/Decimal/corporate-action boundaries), and mechanically rebinds the Gate 0 v4 aggregate candidate tree to a new base SHA without changing the candidate payload or external-attestation status.

Changes:

• Document Qlib as the selected factor-expression and backtest engine, constrained behind libs/factors adapters and TrueAlpha contracts (not a data/semantic authority).
• Update the Gate 1 definition in init.md to explicitly require the pinned Qlib/adapter path for deterministic replay evidence.
• Rebind governance/gate0/manifest-v4.json to a new integration_base_sha and corresponding candidate_tree_sha256 while keeping the candidate payload hash unchanged.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
init.md	Declares Qlib as the selected engine and tightens Gate 1 replay wording to require the pinned Qlib/adapter execution path under TrueAlpha-owned boundaries.
governance/gate0/manifest-v4.json	Updates Gate 0 candidate base/tree binding (integration_base_sha, candidate_tree_sha256) while preserving the candidate payload identity.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[wangzitian0]

Rebased onto current main 838a85c4cea785accf8be2d110b20e9e60b68f45. The two obsolete base-only rebind commits were dropped; the architecture commit was retained and a new exact-base/tree manifest binding was added. New head: 71e5a0fec60944d2d979908d9f8a6699016b585d. Awaiting exact-head ci-required.

[wangzitian0]

Final exact-head verification passed at 71e5a0fec60944d2d979908d9f8a6699016b585d: https://github.com/wangzitian0/truealpha/actions/runs/29394233547. The affected governance and security checks passed, unaffected component jobs were explicitly skipped, terminal ci-required passed, there are no review threads, the base remains current at 838a85c, and GitHub reports MERGEABLE/CLEAN.