pdl-taskmaster 2.4.0__py3-none-any.whl

pdl_taskmaster/runtime/context_compiler.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from hashlib import sha256
+from pathlib import Path
+from typing import Any
+import json
+
+from pdl_taskmaster.runtime.standard_registry import StandardRegistry
+
+
+_AUTO_SYMBOLS = {"OPERATION_ID", "APPLICABLE_STANDARD_CLAUSES", "HIGHER_PRIORITY_CONSTRAINTS"}
+
+
+@dataclass(frozen=True)
+class CompiledProjection:
+    operation: str
+    output_kind: str
+    output_fields: tuple[str, ...]
+    document: dict[str, Any]
+    manifest: dict[str, Any]
+
+    def render(self, bootstrap: str, *, compact: bool = False) -> str:
+        """Render bootstrap + projection document.
+
+        compact=True serializes the document without indentation (~23% smaller);
+        the parsed JSON is identical, so semantics are unchanged. Fixture replay
+        hashes the full rendered prompt, so recorded fixtures must keep the
+        default pretty rendering.
+        """
+        if compact:
+            body = json.dumps(self.document, ensure_ascii=False, separators=(",", ":"))
+        else:
+            body = json.dumps(self.document, ensure_ascii=False, indent=2)
+        return bootstrap.rstrip() + "\n\n" + body + "\n"
+
+
+class ContextCompiler:
+    def __init__(self, repo_root: str | Path, standards_root: str | Path | None = None):
+        self.repo_root = Path(repo_root)
+        from pdl_taskmaster.runtime.normative_store import NormativeStore
+        self.standards_root = Path(standards_root) if standards_root else NormativeStore.resolve_standards_root(self.repo_root)
+        contract_path = NormativeStore.resolve_contract(self.repo_root, "EXECUTION_CONTRACT.json")
+        if not contract_path.is_file():
+            contract_path = self.repo_root / "contracts" / "EXECUTION_CONTRACT.json"
+        self.execution_contract = json.loads(contract_path.read_text(encoding="utf-8"))
+        self.registry = StandardRegistry(self.repo_root, standards_root=self.standards_root)
+
+    def compile(
+        self,
+        operation: str,
+        values: dict[str, Any],
+        *,
+        higher_priority_constraints: Any = None,
+    ) -> CompiledProjection:
+        operations = self.execution_contract["operations"]
+        if operation not in operations:
+            raise ValueError(f"operation:{operation}")
+        spec = operations[operation]
+        include = tuple(spec["include"])
+        # Optional symbols (Phase 9 S4): supplied by the engine only when the
+        # session provides them (e.g. PREVIOUS_DELIVERABLE on chained turns);
+        # absent optional symbols are omitted from the projection entirely so
+        # single-turn projections stay byte-identical (fixture replay safe).
+        optional = tuple(spec.get("optional_include", ()))
+        expected = set(include) - _AUTO_SYMBOLS
+        provided = set(values)
+        missing = expected - provided
+        extra = (provided - expected) - set(optional)
+        if missing:
+            raise ValueError(f"missing_symbols:{sorted(missing)}")
+        if extra:
+            raise ValueError(f"extra_symbols:{sorted(extra)}")
+
+        clauses = self.registry.select(spec["requirements"])
+        clause_values = [
+            {"requirement_id": clause.requirement_id, "clause": clause.text}
+            for clause in clauses
+        ]
+        ordered_inputs: dict[str, Any] = {}
+        for symbol in include:
+            if symbol == "OPERATION_ID":
+                ordered_inputs[symbol] = operation
+            elif symbol == "APPLICABLE_STANDARD_CLAUSES":
+                ordered_inputs[symbol] = clause_values
+            elif symbol == "HIGHER_PRIORITY_CONSTRAINTS":
+                ordered_inputs[symbol] = higher_priority_constraints
+            else:
+                ordered_inputs[symbol] = values[symbol]
+        for symbol in optional:
+            if symbol in provided and values[symbol] is not None:
+                ordered_inputs[symbol] = values[symbol]
+
+        schema_relative = spec.get("output_schema")
+        if not isinstance(schema_relative, str):
+            raise ValueError(f"output_schema:{operation}")
+        schema_path = Path(schema_relative)
+        if schema_path.is_absolute() or ".." in schema_path.parts:
+            raise ValueError(f"output_schema_path:{operation}")
+        full_schema_path = self.repo_root / schema_path
+        if not full_schema_path.is_file() and not schema_path.is_absolute():
+            rel = Path(*schema_path.parts[1:]) if schema_path.parts and schema_path.parts[0] == "scripts" else schema_path
+            pkg_root = Path(__file__).resolve().parents[1]
+            for c in (
+                pkg_root / rel,
+                self.repo_root / "src" / "pdl_taskmaster" / rel,
+                pkg_root / schema_path,
+                self.repo_root / "src" / "pdl_taskmaster" / schema_path,
+                self.repo_root / "scripts" / schema_path,
+            ):
+                if c.is_file():
+                    full_schema_path = c
+                    break
+        if not full_schema_path.is_file():
+            raise ValueError(f"output_schema_missing:{operation}")
+        output_schema = json.loads(full_schema_path.read_text(encoding="utf-8"))
+
+        document: dict[str, Any] = {
+            "operation": operation,
+            "output_kind": spec["output_kind"],
+            "output_schema": output_schema,
+            "operation_inputs": ordered_inputs,
+        }
+        if spec.get("artifact_kind"):
+            document["artifact_kind"] = spec["artifact_kind"]
+
+        clause_digests = {
+            clause.requirement_id: sha256(clause.text.encode("utf-8")).hexdigest()
+            for clause in clauses
+        }
+        manifest = {
+            "operation": operation,
+            "included_symbols": list(include),
+            "excluded_symbols": list(spec.get("exclude", [])),
+            "requirement_ids": list(spec["requirements"]),
+            "clause_sha256": clause_digests,
+            "output_kind": spec["output_kind"],
+            "output_fields": list(spec.get("output_fields", [])),
+            "output_schema": schema_relative,
+            "output_schema_sha256": sha256(full_schema_path.read_bytes()).hexdigest(),
+        }
+        manifest["projection_sha256"] = sha256(
+            json.dumps(document, ensure_ascii=False, sort_keys=True, separators=(",", ":")).encode("utf-8")
+        ).hexdigest()
+        return CompiledProjection(
+            operation=operation,
+            output_kind=spec["output_kind"],
+            output_fields=tuple(spec.get("output_fields", [])),
+            document=document,
+            manifest=manifest,
+        )

pdl_taskmaster/runtime/model_classification.py

@@ -0,0 +1,290 @@
+"""Model and Provider Classification Taxonomy (Track M2).
+
+Prevents cross-tier and cross-provider false equivalences in adversarial evaluation.
+Explicitly distinguishes between:
+  1. Capability Tier (Frontier Flagship vs. Mid-Tier Balanced vs. Lightweight Fast)
+  2. Provider Hosting Class (Direct Dedicated vs. Aggregator BYOK vs. Aggregator Shared Pool)
+  3. Reasoning Architecture (Disabled vs. Native Thinking Traces)
+
+Under this taxonomy, comparing a Mid-Tier Balanced model (e.g. GLM-4.7) to a
+Frontier Flagship model (e.g. DeepSeek-V4-Pro, Claude 3.5 Sonnet, GPT-4o) without
+controlling for capability tier constitutes a methodological false equivalence.
+"""
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from enum import Enum
+from typing import Any
+
+
+class CapabilityTier(str, Enum):
+    FRONTIER_FLAGSHIP = "FRONTIER_FLAGSHIP"  # Tier 1: DeepSeek-V4-Pro, GPT-4o, Claude 3.5 Sonnet, GLM-5.3
+    MID_BALANCED = "MID_BALANCED"            # Tier 2: GLM-4.7, DeepSeek-Flash, Qwen-2.5-72B, Llama-3.3-70B
+    LIGHT_FAST = "LIGHT_FAST"                # Tier 3: GLM-4.7-Flash, Gemini-2.0-Flash, Claude-3.5-Haiku
+
+
+class ProviderHostingClass(str, Enum):
+    DIRECT_FIRST_PARTY = "DIRECT_FIRST_PARTY"  # Direct vendor API with dedicated account quota (e.g. api.deepseek.com)
+    AGGREGATOR_BYOK = "AGGREGATOR_BYOK"        # Aggregator proxy with user's own upstream account key
+    AGGREGATOR_SHARED = "AGGREGATOR_SHARED"    # Aggregator shared public rate-limit pool (e.g. OpenRouter free/shared)
+
+
+@dataclass(frozen=True)
+class ModelClassification:
+    model_id: str
+    display_name: str
+    family: str
+    capability_tier: CapabilityTier
+    tier_rank: int  # 1 = Frontier, 2 = Mid, 3 = Light
+    provider_class: ProviderHostingClass
+    upstream_provider: str
+    reasoning_mode: str
+    recommended_inter_call_delay_s: float
+    comparative_peers: list[str]
+    methodological_notes: str
+
+    def as_dict(self) -> dict[str, Any]:
+        d = asdict(self)
+        d["capability_tier"] = self.capability_tier.value
+        d["provider_class"] = self.provider_class.value
+        return d
+
+
+# Known model taxonomy registry
+_TAXONOMY: dict[str, dict[str, Any]] = {
+    "z-ai/glm-4.7": {
+        "display_name": "GLM-4.7",
+        "family": "Zhipu GLM",
+        "capability_tier": CapabilityTier.MID_BALANCED,
+        "tier_rank": 2,
+        "upstream_provider": "Google Vertex (via OpenRouter)",
+        "recommended_inter_call_delay_s": 3.0,
+        "comparative_peers": ["deepseek-flash", "qwen/qwen-2.5-72b-instruct", "meta-llama/llama-3.3-70b-instruct"],
+        "methodological_notes": (
+            "GLM-4.7 is a Mid-Tier Balanced workhorse. Comparing it to Frontier Flagships "
+            "(e.g. DeepSeek-V4-Pro, Claude-3.5-Sonnet) represents a cross-tier false equivalence. "
+            "Valid comparative baselines must be drawn from Tier 2 peers or paired with GLM-5.3 if available."
+        ),
+    },
+    "z-ai/glm-4.7-flash": {
+        "display_name": "GLM-4.7-Flash",
+        "family": "Zhipu GLM",
+        "capability_tier": CapabilityTier.LIGHT_FAST,
+        "tier_rank": 3,
+        "upstream_provider": "DeepInfra (via OpenRouter)",
+        "recommended_inter_call_delay_s": 1.5,
+        "comparative_peers": ["google/gemini-2.0-flash-001", "anthropic/claude-3.5-haiku"],
+        "methodological_notes": "High-speed Tier 3 lightweight model.",
+    },
+    "deepseek-flash": {
+        "display_name": "DeepSeek-V4.1-Flash",
+        "family": "DeepSeek",
+        "capability_tier": CapabilityTier.MID_BALANCED,
+        "tier_rank": 2,
+        "upstream_provider": "DeepSeek First-Party API",
+        "recommended_inter_call_delay_s": 1.0,
+        "comparative_peers": ["z-ai/glm-4.7", "qwen/qwen-2.5-72b-instruct"],
+        "methodological_notes": "Direct competitor to GLM-4.7 within Tier 2 (Mid-Tier Balanced).",
+    },
+    "deepseek-v4-pro": {
+        "display_name": "DeepSeek-V4-Pro",
+        "family": "DeepSeek",
+        "capability_tier": CapabilityTier.FRONTIER_FLAGSHIP,
+        "tier_rank": 1,
+        "upstream_provider": "DeepSeek First-Party API",
+        "recommended_inter_call_delay_s": 2.0,
+        "comparative_peers": ["claude-3-5-sonnet", "gpt-4o", "z-ai/glm-5.3"],
+        "methodological_notes": "Frontier Flagship (Tier 1). Symmetrically comparable only to other Frontier models.",
+    },
+    "google/gemini-2.0-flash-001": {
+        "display_name": "Gemini 2.0 Flash",
+        "family": "Google Gemini",
+        "capability_tier": CapabilityTier.LIGHT_FAST,
+        "tier_rank": 3,
+        "upstream_provider": "Google (via OpenRouter)",
+        "recommended_inter_call_delay_s": 1.0,
+        "comparative_peers": ["z-ai/glm-4.7-flash", "anthropic/claude-3.5-haiku"],
+        "methodological_notes": "Tier 3 Lightweight fast instruction-follower.",
+    },
+    "google/gemini-2.5-flash": {
+        "display_name": "Gemini 2.5 Flash",
+        "family": "Google Gemini",
+        "capability_tier": CapabilityTier.MID_BALANCED,
+        "tier_rank": 2,
+        "upstream_provider": "Google Vertex (via OpenRouter)",
+        "recommended_inter_call_delay_s": 0.5,
+        "comparative_peers": ["z-ai/glm-4.7", "deepseek-flash", "qwen/qwen-2.5-72b-instruct"],
+        "methodological_notes": (
+            "Google Vertex Tier 2 Mid-Tier Balanced workhorse model with high throughput and native structured outputs. "
+            "Directly comparable to GLM-4.7 and DeepSeek-Flash."
+        ),
+    },
+    "qwen/qwen3-coder-30b-a3b-instruct": {
+        "display_name": "Qwen3 Coder 30B",
+        "family": "Qwen / Alibaba",
+        "capability_tier": CapabilityTier.MID_BALANCED,
+        "tier_rank": 2,
+        "upstream_provider": "Alibaba (via OpenRouter)",
+        "recommended_inter_call_delay_s": 1.0,
+        "comparative_peers": ["z-ai/glm-4.7", "meta-llama/llama-3.3-70b-instruct", "deepseek/deepseek-chat"],
+        "methodological_notes": "Tier 2 Mid-Tier Balanced coding MoE with 256k context. Primary open-weights distillation baseline.",
+    },
+    "meta-llama/llama-3.3-70b-instruct": {
+        "display_name": "Llama 3.3 70B Instruct",
+        "family": "Meta Llama",
+        "capability_tier": CapabilityTier.MID_BALANCED,
+        "tier_rank": 2,
+        "upstream_provider": "Meta (via OpenRouter)",
+        "recommended_inter_call_delay_s": 1.0,
+        "comparative_peers": ["z-ai/glm-4.7", "qwen/qwen3-coder-30b-a3b-instruct", "deepseek/deepseek-chat"],
+        "methodological_notes": "Tier 2 Mid-Tier Balanced dense 70B standard enterprise baseline.",
+    },
+    "deepseek/deepseek-chat": {
+        "display_name": "DeepSeek-V3",
+        "family": "DeepSeek",
+        "capability_tier": CapabilityTier.MID_BALANCED,
+        "tier_rank": 2,
+        "upstream_provider": "DeepSeek (via OpenRouter)",
+        "recommended_inter_call_delay_s": 1.0,
+        "comparative_peers": ["z-ai/glm-4.7", "qwen/qwen3-coder-30b-a3b-instruct", "meta-llama/llama-3.3-70b-instruct"],
+        "methodological_notes": "Tier 2 Mid-Tier Balanced MoE (671B total, 37B active). Direct architectural peer to GLM-4.7's 32B active MoE.",
+    },
+    "z-ai/glm-5.3-flash": {
+        "display_name": "GLM-5.3-Flash",
+        "family": "Zhipu GLM",
+        "capability_tier": CapabilityTier.LIGHT_FAST,
+        "tier_rank": 3,
+        "upstream_provider": "Zhipu AI (via OpenRouter)",
+        "recommended_inter_call_delay_s": 0.5,
+        "comparative_peers": ["openai/gpt-4o-mini", "z-ai/glm-4.7-flash"],
+        "methodological_notes": "Tier 3 Lightweight Fast high-throughput MoE (320B total, 18B active) with 1.3M context.",
+    },
+    "openai/gpt-4o-mini": {
+        "display_name": "GPT-4o-mini",
+        "family": "OpenAI",
+        "capability_tier": CapabilityTier.LIGHT_FAST,
+        "tier_rank": 3,
+        "upstream_provider": "OpenAI (via OpenRouter)",
+        "recommended_inter_call_delay_s": 0.5,
+        "comparative_peers": ["z-ai/glm-5.3-flash", "google/gemini-2.0-flash-001"],
+        "methodological_notes": "Tier 3 Lightweight Fast commercial baseline.",
+    },
+    "anthropic/claude-haiku-4.5": {
+        "display_name": "Claude Haiku 4.5",
+        "family": "Anthropic",
+        "capability_tier": CapabilityTier.FRONTIER_FLAGSHIP,
+        "tier_rank": 1,
+        "upstream_provider": "Anthropic (via OpenRouter)",
+        "recommended_inter_call_delay_s": 1.5,
+        "comparative_peers": ["deepseek-v4-pro", "openai/gpt-4o"],
+        "methodological_notes": "Tier 1 Frontier Flagship lightweight anchor. Frontier upper-bound audit model.",
+    },
+}
+
+
+def classify_model(
+    model_id: str,
+    base_url: str = "https://openrouter.ai/api/v1",
+    reasoning_effort: str = "none",
+) -> ModelClassification:
+    """Classify model capability tier, provider class, and peers."""
+    if "api.deepseek.com" in base_url:
+        provider_class = ProviderHostingClass.DIRECT_FIRST_PARTY
+    elif "openrouter.ai" in base_url:
+        provider_class = ProviderHostingClass.AGGREGATOR_SHARED
+    else:
+        provider_class = ProviderHostingClass.DIRECT_FIRST_PARTY
+
+    reasoning_mode = "disabled" if reasoning_effort in ("none", "", None) else f"enabled({reasoning_effort})"
+
+    meta = _TAXONOMY.get(model_id)
+    if meta:
+        return ModelClassification(
+            model_id=model_id,
+            display_name=meta["display_name"],
+            family=meta["family"],
+            capability_tier=meta["capability_tier"],
+            tier_rank=meta["tier_rank"],
+            provider_class=provider_class,
+            upstream_provider=meta["upstream_provider"],
+            reasoning_mode=reasoning_mode,
+            recommended_inter_call_delay_s=meta["recommended_inter_call_delay_s"],
+            comparative_peers=list(meta["comparative_peers"]),
+            methodological_notes=meta["methodological_notes"],
+        )
+
+    return ModelClassification(
+        model_id=model_id,
+        display_name=model_id,
+        family="Unknown",
+        capability_tier=CapabilityTier.MID_BALANCED,
+        tier_rank=2,
+        provider_class=provider_class,
+        upstream_provider="Generic / Aggregator",
+        reasoning_mode=reasoning_mode,
+        recommended_inter_call_delay_s=3.0,
+        comparative_peers=[],
+        methodological_notes="Uncataloged model evaluated as generic Tier 2.",
+    )
+
+
+def get_proportional_reasoning_mapping(model_id: str) -> dict[str, str | int]:
+    """Return the normative operational reasoning mapping per model class (ADR-0006).
+
+    Operational intent:
+      - BOOTSTRAP_ANALYSIS: Defensive reasoning (untangle injections from tasks)
+      - DRAFT_PROMPT / REVISE_PROMPT: Bounded pre-execution reasoning (entity preservation)
+      - DRAFT_PLAN / REVISE_PLAN / EXECUTE: Zero reasoning (mechanical translation)
+    """
+    mid = model_id.lower()
+    if "glm-4.7" in mid:
+        # Class A: Native effort tiers (Zhipu GLM-4.7)
+        # ADR-0006 as amended by the ADR-0009 benchmark (2026-09-18): EXECUTE
+        # is now the primary semantic generation step (deliverable + Result IR
+        # emission), so it is priced HIGH; DRAFT_EXECUTE (entity-dense brief
+        # drafting) is likewise semantic -> HIGH; EMIT_RESULT_IR is mechanical
+        # correction against explicit host-side errors -> LOW. Translation ops
+        # keep the ratified LOW floor (D25: load-bearing); plan drafting stays
+        # NONE (measured: 144-token plans, zero reasoning, no quality loss).
+        return {
+            "BOOTSTRAP_ANALYSIS": "high",
+            "DRAFT_PROMPT": "low",
+            "REVISE_PROMPT": "low",
+            "DRAFT_PLAN": "none",
+            "REVISE_PLAN": "none",
+            "DRAFT_EXECUTE": "high",
+            "EXECUTE": "high",
+            "EMIT_RESULT_IR": "low",
+        }
+    elif "claude" in mid or "anthropic" in mid:
+        # Class B: Explicit thinking budget (Anthropic Claude 3.5/3.7 Sonnet, Haiku 4.5)
+        return {
+            "BOOTSTRAP_ANALYSIS": 4096,
+            "DRAFT_PROMPT": 1024,
+            "REVISE_PROMPT": 1024,
+            "DRAFT_PLAN": "none",
+            "REVISE_PLAN": "none",
+            "EXECUTE": "none",
+        }
+    elif "thinking" in mid or "r1" in mid or "o1" in mid or "o3" in mid or "o4" in mid:
+        # Class C / Native thinking open-weights / reasoning
+        return {
+            "BOOTSTRAP_ANALYSIS": "high",
+            "DRAFT_PROMPT": "low",
+            "REVISE_PROMPT": "low",
+            "DRAFT_PLAN": "none",
+            "REVISE_PLAN": "none",
+            "EXECUTE": "none",
+        }
+    else:
+        # Class D: Pure instruct / quantized models (Llama 3.3, Qwen Instruct, GPT-4o-mini)
+        # Native API reasoning disabled; deliberative compute provided in-band via schema.
+        return {
+            "BOOTSTRAP_ANALYSIS": "none",
+            "DRAFT_PROMPT": "none",
+            "REVISE_PROMPT": "none",
+            "DRAFT_PLAN": "none",
+            "REVISE_PLAN": "none",
+            "EXECUTE": "none",
+        }
+

pdl_taskmaster/runtime/normative_store.py

@@ -0,0 +1,157 @@
+"""Normative Store & Protocol Version Resolver (ADR-0008).
+
+Formal 4-Tier Precedence Order for Normative Standards:
+1. Priority 1 (Explicit Environment Override): `PDLT_STANDARDS_PATH` environment variable.
+2. Priority 2 (Local Repository Override): `<repo_root>/contracts/` (if containing `CONTRACT_MANIFEST.json`).
+3. Priority 3 (User Normative Store): `~/.pdlt/versions/<version>/contracts/` (ADR-0008 content-addressed store).
+4. Priority 4 (Bundled Canonical Fallback): `pdl_taskmaster.contracts` package data (via `importlib.resources`).
+"""
+from __future__ import annotations
+
+import importlib.resources
+import json
+import os
+from pathlib import Path
+import shutil
+
+
+class NormativeStoreError(RuntimeError):
+    pass
+
+
+class NormativeStore:
+    DEFAULT_VERSION = "v2"
+
+    @classmethod
+    def get_default_store_root(cls) -> Path:
+        env_root = os.environ.get("PDLT_STORE_ROOT")
+        if env_root:
+            return Path(env_root).resolve()
+        return Path.home() / ".pdlt"
+
+    @classmethod
+    def resolve_version(cls, repo_root: str | Path | None = None) -> str:
+        """Resolve pinned protocol version from .pdlt-version or pdlt.json."""
+        if repo_root is not None:
+            root = Path(repo_root).resolve()
+            pin_file = root / ".pdlt-version"
+            if pin_file.is_file():
+                v = pin_file.read_text(encoding="utf-8").strip()
+                if v:
+                    return v
+            cfg_file = root / "pdlt.json"
+            if cfg_file.is_file():
+                try:
+                    data = json.loads(cfg_file.read_text(encoding="utf-8"))
+                    v = data.get("version")
+                    if isinstance(v, str) and v.strip():
+                        return v.strip()
+                except Exception:
+                    pass
+        return cls.DEFAULT_VERSION
+
+    @classmethod
+    def get_bundled_contracts_path(cls) -> Path | None:
+        """Resolve path to package-bundled contracts data directory."""
+        try:
+            bundled = importlib.resources.files("pdl_taskmaster").joinpath("contracts")
+            p = Path(str(bundled))
+            if p.is_dir() and (p / "CONTRACT_MANIFEST.json").is_file():
+                return p
+        except Exception:
+            pass
+        return None
+
+    @classmethod
+    def resolve_standards_root(
+        cls,
+        repo_root: str | Path,
+        version: str | None = None,
+        store_root: str | Path | None = None,
+    ) -> Path:
+        """Resolve directory containing CONTRACT_MANIFEST.json and standards.
+
+        Strict 4-Tier Precedence:
+        1. PDLT_STANDARDS_PATH env var
+        2. Local <repo_root>/contracts/ (if present and valid)
+        3. ~/.pdlt/versions/<version>/contracts/ (if seeded)
+        4. Bundled package data in pdl_taskmaster.contracts
+        """
+        # Tier 1: Explicit environment variable override
+        env_standards = os.environ.get("PDLT_STANDARDS_PATH")
+        if env_standards:
+            p = Path(env_standards).resolve()
+            if p.is_dir() and (p / "CONTRACT_MANIFEST.json").is_file():
+                return p
+
+        # Tier 2: Local repository contracts directory
+        repo_path = Path(repo_root).resolve()
+        local_candidate = repo_path / "contracts"
+        if local_candidate.is_dir() and (local_candidate / "CONTRACT_MANIFEST.json").is_file():
+            return local_candidate
+
+        # Tier 3: Centralized ~/.pdlt store
+        v = version or cls.resolve_version(repo_path)
+        base = Path(store_root).resolve() if store_root else cls.get_default_store_root()
+        user_candidate = base / "versions" / v / "contracts"
+        if user_candidate.is_dir() and (user_candidate / "CONTRACT_MANIFEST.json").is_file():
+            return user_candidate
+
+        # Tier 4: Bundled package data
+        bundled = cls.get_bundled_contracts_path()
+        if bundled is not None:
+            return bundled
+
+        return local_candidate
+
+    @classmethod
+    def resolve_contract(
+        cls,
+        repo_root: str | Path,
+        contract_name: str,
+        version: str | None = None,
+        store_root: str | Path | None = None,
+    ) -> Path:
+        """Resolve a specific contract file (e.g. EXECUTION_CONTRACT.json)."""
+        standards_root = cls.resolve_standards_root(repo_root, version, store_root)
+        target = standards_root / contract_name
+        if target.is_file():
+            return target
+        fallback = Path(repo_root).resolve() / "contracts" / contract_name
+        return fallback
+
+    @classmethod
+    def seed_directory(cls, target_dir: Path, source_dir: Path | None = None) -> Path:
+        """Copy contract files into target directory from local source or bundled data."""
+        target_dir = Path(target_dir).resolve()
+        target_dir.mkdir(parents=True, exist_ok=True)
+
+        src = source_dir
+        if src is None or not (src / "CONTRACT_MANIFEST.json").is_file():
+            src = cls.get_bundled_contracts_path()
+        if src is None or not src.is_dir():
+            raise NormativeStoreError("cannot seed contracts: no valid local or bundled source found")
+
+        for item in src.iterdir():
+            dest = target_dir / item.name
+            if item.is_dir():
+                if dest.exists():
+                    shutil.rmtree(dest)
+                shutil.copytree(item, dest)
+            else:
+                shutil.copy2(item, dest)
+        return target_dir
+
+    @classmethod
+    def seed_store(
+        cls,
+        repo_root: str | Path,
+        version: str = "v2",
+        store_root: str | Path | None = None,
+    ) -> Path:
+        """Seed the centralized ~/.pdlt store from the current repository contracts or bundled data."""
+        repo_path = Path(repo_root).resolve()
+        base = Path(store_root).resolve() if store_root else cls.get_default_store_root()
+        target_dir = base / "versions" / version / "contracts"
+        local_src = repo_path / "contracts" if (repo_path / "contracts").is_dir() else None
+        return cls.seed_directory(target_dir, source_dir=local_src)