feat: add point-in-time investment workflow domain contracts

[Altairpaca]

Sequencing status

Implementation is intentionally deferred behind the stable-release acceptance boundary now documented on main and reflected in roadmap #46. Keep this PR available as the deterministic foundation for the later research-workflow layer, but do not merge it merely to expand scope before the genuine release blockers (#6, #23, #34) are closed.

Goal

Move Clausula from reliable accounting/market primitives toward reproducible investment workflows without introducing opaque automated investment decisions.

Change

• add InvestmentWorkflow, WorkflowInputRef, WorkflowRun, and WorkflowArtifact domain contracts;
• enforce point-in-time semantics (effective_at <= known_at <= workflow as_of) to reject hindsight;
• require immutable SHA-256 provenance for workflow inputs and artifacts;
• enforce workflow run status/completion invariants;
• verify artifacts consume only digests already recorded by the run;
• export the contracts from clausula.domain;
• add deterministic tests for reproducibility, hindsight rejection, completion state and artifact provenance;
• document the intended investment workflow foundation.

Boundary

No model-generated trade decision or execution authority is introduced. These are deterministic workflow/provenance primitives for later research, thesis and decision workflows.

Merge gate

Re-review/rebase this branch after stable-release acceptance. At that point, verify that the workflow contracts reuse the final canonical research/artifact/accounting identities rather than creating a parallel truth system.

Refs #40 #46

[Altairpaca]

2026-09-10 design audit — converted to Draft intentionally. The point-in-time/fingerprint direction is useful, but this branch should not be rebased-and-merged mechanically after the release gate.

Required redesign before Ready for Review:

1. Reuse canonical SourceArtifact / ResearchDocument-Claim-Evidence-Thesis identities instead of letting WorkflowArtifact(uri, sha256, ...) become a parallel artifact truth system.
2. Separate workflow definition/version from execution-run provenance. A reusable workflow definition should not need to pretend it was imported from a research artifact unless that is genuinely its source.
3. Make run inputs typed canonical references resolved by Clausula services/capabilities; do not trust an Agent/client to assert an arbitrary object digest as provenance.
4. Record tool/capability version plus optional model/agent/config identity as execution provenance, never financial truth.
5. Preserve historical as_of/known_as_of reconstruction while distinguishing the historical knowledge cutoff from the later wall-clock time at which a replay/workflow was executed.
6. Produced analysis/research output should land in existing immutable artifact/research machinery; Recommendation remains a separate draft lifecycle.
7. Add tests proving no second truth system, no client-forged input provenance, deterministic fingerprint/replay where inputs/tools are deterministic, and no hindsight.

Keep the existing tests as useful specification evidence, but treat the current domain types as a prototype rather than the final schema. Activation remains behind #23/#34.

[Altairpaca]

Additional temporal blocker found in the 2026-09-10 audit: the current assert_point_in_time() hard-codes effective_at <= known_at. That is not a valid universal bitemporal invariant for Clausula. A fact may be known before it becomes effective (e.g. a corporate action announced on Jan 1 and effective Jan 10, a scheduled policy change, or other future-effective information). No-hindsight should constrain the knowledge cutoff (known_at <= known_as_of / workflow knowledge cutoff) and separately constrain effective-state selection where the workflow requires an as_of business-time cutoff; it should not require facts to become effective before they can be known.

Before this PR becomes Ready for Review, replace the single ordered-time assertion with explicit bitemporal selection semantics and add a regression case for a known-before-effective fact. This is another reason not to merge the current prototype unchanged.