Add experimental CorDA-PCA, S-space, and Linear-AcT controls

[wassname]

Adding 3 interesting steering method from https://github.com/wassname/steering-lite which may be promising on upcoming evals

Summary

• Add three experimental state controls: a CorDA-derived PCA activation-steering adaptation, a weight-SVD S-space variant, and coordinate-wise Linear-AcT transport.

Checks

• pytest tests/controls/ -q — 2059 passed, 329 skipped (peft warnings?)
• pytest tests/core/test_spipe_codec.py tests/core/test_spipe_identity.py tests/controls/test_spipe_freeze_state.py -q — 42 passed
• mkdocs build
• changed-file pre-commit

[Copilot]

🟡 Changes recommended

Unresolved moderate findings remain in the new controls, including frozen-form provenance and repeated device-transfer issues.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds experimental CorDA-PCA, S-space, and Linear-AcT state controls, plus per-artifact SPipe fit provenance.

Changes:

• Adds three state-control implementations with tests and registrations.
• Extends frozen-artifact provenance handling.
• Adds reference documentation, catalog entries, and navigation updates.

File summaries

File	Summary	Final review notes
tests/controls/test_sspace.py	S-space formula, dtype, pipeline, and freeze tests.	No final comments.
tests/controls/test_linear_act.py	Linear-AcT fitting, validation, and freeze tests.	No final comments.
tests/controls/test_corda_pca.py	CorDA-PCA fitting and pipeline tests.	Nit (1 vote): Add fit-digest round-trip and edited-recipe coverage.
steerability/spipe/freeze.py	Per-entry artifact provenance handling.	No final comments.
steerability/algorithms/state_control/sspace/control.py	S-space control implementation.	Moderate (3 votes): Add the required class-docstring reference. Moderate (2 votes): Reuse device/dtype-correct artifacts instead of transferring them on every hook invocation.
steerability/algorithms/state_control/sspace/args.py	S-space arguments.	No final comments.
steerability/algorithms/state_control/sspace/__init__.py	S-space registration.	No final comments.
steerability/algorithms/state_control/linear_act/control.py	Linear-AcT control implementation.	Moderate (3 votes): Return no fit identity for frozen affine controls. Nit (3 votes): Add the required class-docstring reference. Moderate (2 votes): Reuse a device/dtype-correct runtime copy.
steerability/algorithms/state_control/linear_act/args.py	Linear-AcT arguments.	No final comments.
steerability/algorithms/state_control/linear_act/__init__.py	Linear-AcT registration.	No final comments.
steerability/algorithms/state_control/corda_pca/control.py	CorDA-PCA control implementation.	Moderate (1 vote): Mark every exported module path explicitly for provenance. Moderate (3 votes): Return no fit identity for precomputed directions. Nit (3 votes): Add the required class-docstring reference. Moderate (2 votes): Reuse a materialized device/dtype-correct direction. Nit (1 vote): Add frozen-provenance regression coverage.
steerability/algorithms/state_control/corda_pca/args.py	CorDA-PCA arguments.	No final comments.
steerability/algorithms/state_control/corda_pca/__init__.py	CorDA-PCA registration.	No final comments.
steerability/algorithms/core/base_control.py	Exported artifact-class override API.	No final comments.
docs/reference/algorithms/state_control/sspace.md	S-space API reference.	No final comments.
docs/reference/algorithms/state_control/linear_act.md	Linear-AcT API reference.	No final comments.
docs/reference/algorithms/state_control/corda_pca.md	CorDA-PCA API reference.	No final comments.
docs/concepts/controls.md	State-control catalog entries.	Nit (2 votes): Add demonstration notebooks and examples/index.md entries.
docs/.nav.yml	Documentation navigation entries.	Nit (1 vote): Add demonstration notebooks and index links, or defer navigation registration.
.gitignore	Ignores .local/.	No final comments.

Review details

Suppressed comments (4)

docs/.nav.yml:114

• These new controls are added to the published algorithm navigation without demonstration notebooks or entries in examples/index.md. The repository's method-authoring documentation requires every new control to ship a notebook and an index entry, so the documentation surface is incomplete; add those files and links or defer registering these methods until they exist.

            - CorDA-derived PCA: reference/algorithms/state_control/corda_pca.md
            - S-space: reference/algorithms/state_control/sspace.md
            - Linear-AcT: reference/algorithms/state_control/linear_act.md

steerability/algorithms/state_control/corda_pca/control.py:88

• When calibration covers multiple module paths, export_state() emits one tensor per path but this declares only one implicit direction fit. The freeze walk consumes implicit fits one at a time, so only the first resolved artifact gets source/fit_digest; mark every exported key explicitly as direction (as the calibrated controls below do) so provenance is retained for all modules.

    def steer_fits(self) -> tuple[tuple[str, str], ...]:
        return () if self.directions is not None else (("corda_pca", "direction"),)

steerability/algorithms/state_control/corda_pca/control.py:91

• This adds export_state()/frozen_form() and advertises a fit artifact, but test_corda_pca.py only covers fitting and generation. There is no round-trip or edited-recipe test for the fit digest, so the PR's frozen-provenance guarantee can regress silently; add coverage analogous to the S-space and Linear-AcT tests.

    def steer_fits(self) -> tuple[tuple[str, str], ...]:
        return () if self.directions is not None else (("corda_pca", "direction"),)

    def export_state(self) -> dict[str, torch.Tensor]:
        return self.fitted_directions

steerability/algorithms/state_control/sspace/control.py:121

• For a frozen artifacts control, steer_fits() is empty but this method still returns a non-None identity. The freeze walk consequently labels recipe-supplied tensors with a fit digest and can mark the unused rank field stale; return None when artifacts is supplied.

    def fit_identity(self) -> tuple:
        return self.positive_outputs, self.negative_outputs, self.rank

• Files reviewed: 19/20 changed files
• Comments generated: 9
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

Unresolved moderate findings remain around model-fingerprint validation and the CorDA-PCA normalization switch.

Get a fresh assessment by requesting another Copilot review.

Review details

Suppressed comments (3)

steerability/algorithms/state_control/corda_pca/control.py:44

• pcs[0] is already a unit right singular vector from torch.linalg.svd, so normalize=False and normalize=True produce the same PCA direction up to the 1e-8 denominator. The public argument and its docstring promise a meaningful normalization switch; either remove it/document it as inert or define the unnormalized branch with an explicit PCA magnitude.

    direction = pcs[0]
    direction = direction * torch.sign(differences.mean(0) @ direction + 1e-8)
    if normalize:
        direction = direction / (direction.norm() + 1e-8)
    return ((direction * sqrt_s) @ u.T).contiguous()

steerability/algorithms/state_control/corda_pca/control.py:62

• The Reference block ends with the steering-lite implementation link, while control docstrings in this repository terminate with the paper citation (for example, steerability/algorithms/state_control/caa/control.py:35-39). Move the implementation provenance before the terminal CorDA paper reference so the generated API documentation follows the established convention.

        - Implementation: wassname, steering-lite `corda_pca.py` at `0a064ba`.
          https://github.com/wassname/steering-lite/blob/0a064ba0c23a4998637ff41c5ab0fb5ca50a4271/src/steering_lite/variants/corda_pca.py

steerability/algorithms/state_control/linear_act/control.py:94

• The Reference block ends with the steering-lite implementation link, while control docstrings in this repository terminate with the paper citation (for example, steerability/algorithms/state_control/caa/control.py:35-39). Move the implementation provenance before the terminal Linear-AcT paper reference so the generated API documentation follows the established convention.

        - Implementation: wassname, steering-lite `linear_act.py` at `0a064ba`.
          https://github.com/wassname/steering-lite/blob/0a064ba0c23a4998637ff41c5ab0fb5ca50a4271/src/steering_lite/variants/linear_act.py

• Files reviewed: 24/25 changed files
• Comments generated: 4
• Review effort level: Lite

[Copilot]

🟡 Changes recommended

Fix the critical Linear-AcT recipe-only freeze path, which currently raises IndexError.

Get a fresh assessment by requesting another Copilot review.

Review details

• Files reviewed: 28/29 changed files
• Comments generated: 1
• Review effort level: Lite

[wassname]

done