[truealpha-factors] Implement safe Qlib expression contract

[wangzitian0]

Scope

Implement E0 for #189 over the frozen S8 corpus. This PR accepts experimental code only; it leaves #189 open and approves no product factor, real data, provider, replay, persistence, or release path.

The slice adds:

• Qlib-independent frozen typed AST, feature-binding, builtin operator-registry, compiled-expression, and execution-binding contracts;
• deterministic Decimal rendering, content-addressed identities, AST/node/lookback/resource limits, and stale-reference rejection;
• a compiler that emits canonical Qlib syntax only from approved typed nodes;
• a runtime adapter with no raw string input, no custom operators, and pinned Qlib 0.9.7 parsing;
• an independent evaluator that matches actual Qlib output for arithmetic, Ref, Mean, and null behavior on the frozen matrix.

The Gate 0-frozen truealpha_contracts/__init__.py remains unchanged. Provisional callers import the dedicated module directly; public re-export waits for a stable handoff and Gate 0 candidate rebind.

Verification

• uv sync --project libs/factors/qlib-runtime --all-groups --frozen
• uv run pytest libs/contracts/tests/test_qlib_expression.py -q (14 passed)
• uv run --project libs/factors/qlib-runtime pytest libs/factors/tests/batches/qlib_expression_contract_tiny -q (15 passed)
• targeted Ruff passed
• uv run mypy passed (95 source files)
• make issue-graph-check passed
• pre-rebase fresh-database make check passed (714 passed, 5 skipped); exact rebased head is covered by PR CI

Issue: #189

[wangzitian0]

@copilot review

[Copilot]

Pull request overview

This PR introduces a Qlib-independent, content-addressed typed expression contract and a “safe compiler boundary” that emits canonical Qlib syntax only from approved typed AST nodes, then validates parity against pinned Qlib behavior using the frozen S8 synthetic corpus.

Changes:

• Add truealpha_contracts.qlib_expression models for typed AST nodes, operator registry, compiled expressions, and execution bindings/evidence (all strict/frozen and content-addressed).
• Add the S8 tiny runtime compiler/adapter in libs/factors plus a Qlib-parity test suite (including an independent evaluator oracle).
• Advance S8 batch governance metadata to reflect E0 acceptance and move the batch forward to E1 work.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
libs/contracts/src/truealpha_contracts/qlib_expression.py	Defines the Qlib-independent typed AST + operator registry + identity/binding contracts with strict validation and hashing.
libs/contracts/tests/test_qlib_expression.py	Validates contract canonicalization, injection resistance, limits, and identity stability against a frozen corpus.
libs/factors/src/factors/batches/qlib_expression_contract_tiny/compiler.py	Implements the compiler boundary (typed AST → canonical Qlib field) and execution evidence binding.
libs/factors/src/factors/batches/qlib_expression_contract_tiny/init.py	Exposes the S8 compiler/evidence surface for provisional callers without changing the Gate 0 export.
libs/factors/tests/batches/qlib_expression_contract_tiny/test_compiler.py	Tests compiler rejection paths, lookback validation, and execution-vs-semantic identity separation.
libs/factors/tests/batches/qlib_expression_contract_tiny/test_qlib_runtime.py	Validates oracle parity vs Qlib runtime and ensures Qlib sees only compiler output.
governance/batches/S8-qlib-factor-expression.v1.json	Updates batch status/revision and records E0 acceptance state plus acceptance commands.
governance/vision-issue-graph.json	Updates the Vision graph batch entry to match the new manifest hash/status/target rung.

---

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