runtime-labs-contracts 0.1.0__tar.gz

runtime_labs_contracts-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+.venv/
+.env
+.env.*
+!.env.example
+.pytest_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+*.jsonl
+.scanner-recordings/
+.scanner-cache/
+.scanner-checkpoints/
+.scanner-runs/
+
+# Local app state and frontend build artifacts
+.runtime-labs/
+node_modules/
+*.tsbuildinfo
+playwright-report/
+test-results/

runtime_labs_contracts-0.1.0/PKG-INFO

@@ -0,0 +1,26 @@
+Metadata-Version: 2.5
+Name: runtime-labs-contracts
+Version: 0.1.0
+Summary: Shared validation models and deployment contracts for Runtime Labs
+Project-URL: Repository, https://github.com/arpandesai0/runtime-labs
+Requires-Python: <3.14,>=3.11
+Requires-Dist: pydantic<3,>=2.7
+Provides-Extra: pubsub
+Requires-Dist: google-cloud-pubsub<3,>=2.27; extra == 'pubsub'
+Description-Content-Type: text/markdown
+
+# Runtime Labs contracts
+
+Shared validation models, deployment manifests, source identities, and messaging
+contracts used by the Runtime Labs SDK and services.
+
+Requires Python 3.11, 3.12, or 3.13.
+
+```bash
+pip install runtime-labs-contracts
+```
+
+Installing `runtime-labs-sdk` also installs this package automatically.
+
+See the [Runtime Labs repository](https://github.com/arpandesai0/runtime-labs)
+for SDK usage and development instructions.

runtime_labs_contracts-0.1.0/README.md

@@ -0,0 +1,15 @@
+# Runtime Labs contracts
+
+Shared validation models, deployment manifests, source identities, and messaging
+contracts used by the Runtime Labs SDK and services.
+
+Requires Python 3.11, 3.12, or 3.13.
+
+```bash
+pip install runtime-labs-contracts
+```
+
+Installing `runtime-labs-sdk` also installs this package automatically.
+
+See the [Runtime Labs repository](https://github.com/arpandesai0/runtime-labs)
+for SDK usage and development instructions.

runtime_labs_contracts-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "runtime-labs-contracts"
+version = "0.1.0"
+description = "Shared validation models and deployment contracts for Runtime Labs"
+readme = "README.md"
+requires-python = ">=3.11,<3.14"
+dependencies = ["pydantic>=2.7,<3"]
+
+[project.optional-dependencies]
+pubsub = ["google-cloud-pubsub>=2.27,<3"]
+
+[project.urls]
+Repository = "https://github.com/arpandesai0/runtime-labs"
+
+[tool.hatch.build.targets.wheel]
+only-include = ["src"]
+sources = ["src"]

runtime_labs_contracts-0.1.0/src/asset_contracts.py

@@ -0,0 +1,196 @@
+"""The scanner's discovery output: assets, their metadata, and direct asset edges.
+
+This is the only graph the scanner publishes for downstream consumers. The data
+processing pipelines build every view (UI, evals, risk, governance) from it and
+never read source code themselves.
+
+Rules the scanner guarantees:
+
+- Every asset and edge is backed by source evidence the verifier re-proved at the
+  scanned commit. Nothing comes from names, runtime traces or model confidence.
+- Edges are single direct relations. A route that reaches a model through two
+  helper functions is three edges, not one; consumers traverse when they need to.
+- ``asset_id`` is stable across scans while the asset's identity is unchanged
+  (kind plus symbol, registration label, route or call ordinal), so history,
+  diffs and trace links survive unrelated edits. Line ranges live in ``anchor``.
+- Traces are not assets. A span links to an asset through ``runtime_ids``, the
+  deployment-manifest node IDs the SDK stamps on spans.
+"""
+
+from typing import Any, Literal
+
+from contracts import SourceLocation, StrictModel
+from pydantic import Field, model_validator
+
+AssetKind = Literal[
+    "Endpoint",  # an HTTP route handler
+    "Workflow",  # a compiled agent graph (identified by the factory that builds it)
+    "WorkflowNode",  # one registered node of a workflow
+    "Agent",  # an agent object outside a workflow framework
+    "Tool",  # a callable exposed to a model
+    "ModelCall",  # one model invocation site
+    "DataStore",  # a persisted entity such as an ORM model
+    "Function",  # plain code that directly links other assets
+]
+
+EdgeKind = Literal[
+    "contains",  # Workflow -> WorkflowNode
+    "starts",  # Workflow -> WorkflowNode it enters first (-> itself: may end at once)
+    "ends",  # WorkflowNode -> Workflow it can finish
+    "transitions_to",  # WorkflowNode -> WorkflowNode (control flow)
+    "delegates_to",  # WorkflowNode -> Workflow it runs as a subgraph
+    "invokes",  # direct call between code assets
+    "calls_model",  # asset whose body contains the ModelCall
+    "offers_tool",  # ModelCall -> Tool passed to it, or Agent -> Tool its model can run
+    "reads",  # asset -> DataStore it queries
+]
+
+
+class SourceAnchor(StrictModel):
+    path: str
+    location: SourceLocation
+
+
+class _Metadata(StrictModel):
+    description: str | None = None
+    signature: str | None = None
+    return_annotation: str | None = None
+    asynchronous: bool | None = None
+
+
+class EndpointMetadata(_Metadata):
+    method: str
+    route: str
+    handler: str
+    framework: str | None = None  # the library spec that recognized the route
+
+
+class WorkflowMetadata(_Metadata):
+    factory: str
+    state_type: str | None = None
+    framework: str | None = None  # the library spec that recognized the graph
+
+
+class WorkflowNodeMetadata(_Metadata):
+    label: str
+    callback: str
+    subgraph: bool = False
+    state_type: str | None = None
+
+
+class AgentMetadata(_Metadata):
+    rule: str | None = None
+    # True for code that makes one model call and uses the answer (a summary or a
+    # classification), rather than looping on the model's output.
+    single_call: bool | None = None
+    # What the code asks the model, for summaries: its bounded source, enclosing
+    # docstrings and the text constants (prompts, questions) it uses.
+    context: dict[str, Any] | None = None
+
+
+class ToolMetadata(_Metadata):
+    rule: str | None = None
+
+
+class ModelCallMetadata(_Metadata):
+    """AI configuration as source values: each says whether it is a literal, a
+    template with variables, or an unresolved expression. The description and
+    signature are the enclosing function's."""
+
+    enclosing_symbol: str
+    call_ordinal: int | None = None
+    provider: str | None = None
+    operation: str | None = None
+    # The function that makes the provider call, when this site reaches it through
+    # the application's own wrappers (``through``, outermost first).
+    boundary: str | None = None
+    through: list[str] = Field(default_factory=list)
+    model: dict[str, Any] | None = None
+    prompts: list[dict[str, Any]] = Field(default_factory=list)
+    tools: dict[str, Any] | None = None
+    settings: dict[str, Any] = Field(default_factory=dict)
+    configuration: dict[str, Any] | None = None
+
+
+class DataStoreMetadata(_Metadata):
+    framework: str | None = None
+
+
+class FunctionMetadata(_Metadata):
+    pass
+
+
+METADATA = {
+    "Endpoint": EndpointMetadata,
+    "Workflow": WorkflowMetadata,
+    "WorkflowNode": WorkflowNodeMetadata,
+    "Agent": AgentMetadata,
+    "Tool": ToolMetadata,
+    "ModelCall": ModelCallMetadata,
+    "DataStore": DataStoreMetadata,
+    "Function": FunctionMetadata,
+}
+
+
+class Asset(StrictModel):
+    asset_id: str
+    kind: AssetKind
+    name: str
+    qualified_symbol: str
+    parent_id: str | None = None
+    anchor: SourceAnchor
+    evidence_ids: list[str] = Field(min_length=1)
+    runtime_ids: list[str] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @model_validator(mode="after")
+    def typed_metadata(self):
+        self.metadata = METADATA[self.kind].model_validate(self.metadata).model_dump(
+            exclude_none=True
+        )
+        return self
+
+
+class AssetEdge(StrictModel):
+    edge_id: str
+    kind: EdgeKind
+    from_asset_id: str
+    to_asset_id: str
+    evidence_ids: list[str] = Field(min_length=1)
+    attributes: dict[str, Any] = Field(default_factory=dict)
+
+
+class DiscoveryGap(StrictModel):
+    """Something the scanner saw but could not prove, kept so coverage is honest."""
+
+    code: str
+    message: str
+    anchor: SourceAnchor | None = None
+
+
+class SourceRemote(StrictModel):
+    """Where the scanned checkout lives on its Git host, so consumers can link to source."""
+
+    url: str  # normalized remote, e.g. "github.com/acme/app"
+    subdirectory: str = ""  # the scanned directory within that repository; "" at its root
+
+
+class AssetGraph(StrictModel):
+    schema_version: Literal[1] = 1
+    repository_id: str
+    commit_sha: str
+    remote: SourceRemote | None = None
+    scanner_version: str
+    assets: list[Asset]
+    edges: list[AssetEdge]
+    gaps: list[DiscoveryGap] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def closed_graph(self):
+        ids = {asset.asset_id for asset in self.assets}
+        if len(ids) != len(self.assets):
+            raise ValueError("Duplicate asset IDs")
+        for edge in self.edges:
+            if edge.from_asset_id not in ids or edge.to_asset_id not in ids:
+                raise ValueError(f"Edge {edge.edge_id} references an unknown asset")
+        return self

runtime_labs_contracts-0.1.0/src/contracts.py

@@ -0,0 +1,150 @@
+"""Versioned wire contracts for source discovery and runtime attribution.
+
+These models are shared across scanner output, instrumentation manifests, and
+trace correlation. Extra fields are rejected so incompatible producers cannot
+silently change the meaning of a stored graph or span identity.
+"""
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+class StrictModel(BaseModel):
+    """Base contract that rejects fields outside the declared schema."""
+
+    model_config = ConfigDict(extra="forbid")
+
+
+NodeKind = Literal["Agent", "Tool", "Workflow", "ModelCallSite", "Model", "Provider", "Service"]
+EdgeKind = Literal[
+    "DEFINED_IN",
+    "CONTAINS",
+    "REGISTERS_TOOL",
+    "INVOKES_AGENT",
+    "INVOKES_TOOL",
+    "CALLS_MODEL",
+]
+EvidenceKind = Literal["declared", "statically_inferred"]
+SupportState = Literal["supported", "unresolved", "unsupported"]
+
+
+class SourceLocation(StrictModel):
+    """One-based source line range with zero-based columns."""
+
+    start_line: int = Field(ge=1)
+    start_col: int = Field(ge=0)
+    end_line: int = Field(ge=1)
+    end_col: int = Field(ge=0)
+
+
+class Evidence(StrictModel):
+    """The scanner rule and source range supporting a discovered fact."""
+
+    rule: str
+    adapter: str
+    classification: EvidenceKind
+    path: str
+    location: SourceLocation
+
+
+class SourceNode(StrictModel):
+    """A source-level component or call site tied to its file and fingerprint."""
+
+    node_id: str
+    kind: NodeKind
+    qualified_symbol: str
+    path: str
+    location: SourceLocation
+    source_digest: str
+    semantic_fingerprint: str
+    operation: str | None = None
+    call_ordinal: int | None = Field(default=None, ge=1)
+    support: SupportState = "supported"
+    evidence: list[Evidence] = Field(min_length=1)
+
+
+class SourceEdge(StrictModel):
+    """A directed relationship between two nodes in the same source graph."""
+
+    from_node_id: str
+    to_node_id: str
+    kind: EdgeKind
+    evidence: Evidence
+
+
+class ScanDiagnostic(StrictModel):
+    """A skipped, unsupported, or unresolved source pattern reported by a scan."""
+
+    code: str
+    path: str
+    message: str
+    location: SourceLocation | None = None
+
+
+class SourceGraph(StrictModel):
+    """The scanner's versioned graph for one repository snapshot."""
+
+    schema_version: Literal[1] = 1
+    project_id: str
+    repository_id: str
+    graph_version_id: str
+    commit_sha: str | None
+    dirty: bool
+    scanner_version: str
+    nodes: list[SourceNode]
+    edges: list[SourceEdge]
+    diagnostics: list[ScanDiagnostic] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def check_references(self) -> "SourceGraph":
+        """Reject duplicate nodes and edges that point outside this graph."""
+
+        ids = [node.node_id for node in self.nodes]
+        if len(ids) != len(set(ids)):
+            raise ValueError("Duplicate source node IDs")
+        known = set(ids)
+        for edge in self.edges:
+            if edge.from_node_id not in known or edge.to_node_id not in known:
+                raise ValueError("Source edge references an absent node")
+        return self
+
+
+class ManifestTarget(StrictModel):
+    """A source node and trusted SDK hook selected for instrumentation."""
+
+    node_id: str
+    kind: NodeKind
+    strategy: Literal["provider_hook", "framework_hook", "function_hook"]
+    hook_id: str
+    qualified_symbol: str
+    source_digest: str
+    expected_span_kind: str
+
+
+class InstrumentationManifest(StrictModel):
+    """A revision-bound set of hooks for a supported customer deployment."""
+
+    schema_version: Literal[1] = 1
+    project_id: str
+    repository_id: str
+    graph_version_id: str
+    commit_sha: str
+    manifest_id: str
+    min_sdk_version: str
+    targets: list[ManifestTarget]
+
+
+class SpanIdentity(StrictModel):
+    """Identifiers needed to link an observed span to its source revision."""
+
+    schema_version: Literal[1] = 1
+    project_id: str
+    repository_id: str | None = None
+    commit_sha: str | None = None
+    graph_version_id: str | None = None
+    manifest_id: str | None = None
+    node_id: str | None = None
+    trace_id: str
+    span_id: str
+    parent_span_id: str | None = None

runtime_labs_contracts-0.1.0/src/deployment_contracts.py

@@ -0,0 +1,102 @@
+"""Metadata-only source identities for future runtime telemetry attribution."""
+
+from pathlib import PurePosixPath
+from typing import Literal
+
+from contracts import SourceLocation, StrictModel
+from pydantic import Field, field_validator, model_validator
+
+RuntimeEntityKind = Literal["Workflow", "Agent", "Tool", "ModelCallSite", "APIEndpoint"]
+RuntimeRelationshipKind = Literal["CONTAINS", "REGISTERS_TOOL", "CALLS_MODEL", "ROUTES_TO"]
+
+
+class ManifestEvidence(StrictModel):
+    """Source proof reference; its revision is the enclosing manifest's revision."""
+
+    evidence_id: str
+    path: str
+    location: SourceLocation
+    source_digest: str = Field(pattern=r"^[0-9a-f]{64}$")
+    adapter: str
+    adapter_version: str
+    verifier_version: str
+
+    @field_validator("path")
+    @classmethod
+    def repository_relative_path(cls, value):
+        path = PurePosixPath(value)
+        if path.is_absolute() or ".." in path.parts or "\\" in value or not path.parts:
+            raise ValueError("Manifest source paths must be repository relative")
+        return value
+
+    @model_validator(mode="after")
+    def ordered_range(self):
+        loc = self.location
+        if (loc.end_line, loc.end_col) <= (loc.start_line, loc.start_col):
+            raise ValueError("Manifest source ranges must be nonempty and ordered")
+        return self
+
+
+class ManifestEntity(StrictModel):
+    node_id: str
+    kind: RuntimeEntityKind
+    qualified_symbol: str
+    source: ManifestEvidence
+    evidence_ids: list[str] = Field(min_length=1)
+    verification_status: Literal["verified_source"] = "verified_source"
+    framework: Literal["langgraph", "fastapi"] | None = None
+    provider: Literal["google"] | None = None
+    operation: str | None = None
+    model: str | None = None
+
+    @model_validator(mode="after")
+    def call_site_metadata(self):
+        if self.kind == "ModelCallSite":
+            if not self.provider:
+                raise ValueError("Model call sites require a verified provider")
+        elif any(value is not None for value in (self.model, self.operation)):
+            raise ValueError("Only model call sites may carry call-site metadata")
+        return self
+
+
+class ManifestRelationship(StrictModel):
+    relationship_id: str
+    kind: RuntimeRelationshipKind
+    from_node_id: str
+    to_node_id: str
+    evidence_ids: list[str] = Field(min_length=1)
+    verification_status: Literal["verified_source"] = "verified_source"
+
+
+class DeploymentManifest(StrictModel):
+    """V1 deployment metadata compiled solely from a published EvidenceGraph."""
+
+    schema_version: Literal[1] = 1
+    repository_id: str
+    commit_sha: str
+    scanner_version: str
+    entities: list[ManifestEntity]
+    relationships: list[ManifestRelationship]
+    evidence: list[ManifestEvidence]
+
+    @model_validator(mode="after")
+    def check_references(self):
+        nodes = {entity.node_id: entity for entity in self.entities}
+        proof = {item.evidence_id: item for item in self.evidence}
+        if len(nodes) != len(self.entities) or len(proof) != len(self.evidence):
+            raise ValueError("Duplicate manifest node or evidence IDs")
+        if len({r.relationship_id for r in self.relationships}) != len(self.relationships):
+            raise ValueError("Duplicate manifest relationship IDs")
+        for item in [*self.entities, *self.relationships]:
+            if not set(item.evidence_ids) <= proof.keys():
+                raise ValueError("Unknown manifest evidence reference")
+        for entity in self.entities:
+            if (
+                proof.get(entity.source.evidence_id) != entity.source
+                or entity.source.evidence_id not in entity.evidence_ids
+            ):
+                raise ValueError("Entity source must reference its manifest evidence")
+        for relationship in self.relationships:
+            if relationship.from_node_id not in nodes or relationship.to_node_id not in nodes:
+                raise ValueError("Manifest relationship references an absent node")
+        return self

runtime_labs_contracts-0.1.0/src/evidence_contracts.py

@@ -0,0 +1,256 @@
+"""V2 evidence contracts; v1 source graphs and runtime span contracts stay unchanged."""
+
+from typing import Any, Literal
+
+from contracts import SourceLocation, StrictModel
+from pydantic import Field, model_validator
+
+ClaimStatus = Literal["proposed", "verified_source", "partial", "unresolved", "contradicted"]
+Transform = Literal[
+    "field_copy",
+    "argument_binding",
+    "string_format",
+    "lookup",
+    "serialization",
+    "derived_output",
+    "return_binding",
+    "state_update",
+    "state_read",
+    "transformation",
+]
+
+
+class EvidenceRef(StrictModel):
+    evidence_id: str
+    evidence_type: Literal["source", "runtime", "synthetic_test"] = "source"
+    repository_id: str
+    commit_sha: str
+    path: str
+    file_digest: str
+    location: SourceLocation
+    adapter: str
+    adapter_version: str = "2"
+    verifier_version: str = "2"
+    task_id: str = "index"
+    deployment_id: str | None = None
+    span_id: str | None = None
+    test_id: str | None = None
+
+    @model_validator(mode="after")
+    def check_evidence_type(self):
+        if self.evidence_type == "runtime" and not (self.deployment_id and self.span_id):
+            raise ValueError("Runtime evidence requires deployment and span IDs")
+        if self.evidence_type == "synthetic_test" and not self.test_id:
+            raise ValueError("Synthetic evidence requires a test ID")
+        return self
+
+
+class Port(StrictModel):
+    port_id: str
+    symbol_id: str
+    name: str
+    kind: Literal["parameter", "field", "value", "argument", "return", "state", "model_output"]
+    evidence: EvidenceRef
+
+
+class IndexSymbol(StrictModel):
+    symbol_id: str
+    qualified_name: str
+    kind: str
+    parameters: list[str] = Field(default_factory=list)
+    parameter_types: dict[str, str] = Field(default_factory=dict)
+    return_type: str | None = None
+    bases: list[str] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    evidence: EvidenceRef
+
+
+class IndexFact(StrictModel):
+    """Language-neutral syntax/semantic facts; only adapters may produce these."""
+
+    fact_id: str
+    kind: Literal[
+        "import",
+        "reference",
+        "call",
+        "assignment",
+        "argument_binding",
+        "return",
+        "flow",
+        "asset",
+        "relationship",
+        "registration",
+        "gap",
+    ]
+    symbol_id: str
+    source: str = ""
+    target: str = ""
+    transform: Transform | None = None
+    guard: str | None = None
+    attributes: dict[str, Any] = Field(default_factory=dict)
+    evidence: list[EvidenceRef] = Field(min_length=1)
+
+
+class IndexBundle(StrictModel):
+    schema_version: Literal[2] = 2
+    repository_id: str
+    commit_sha: str
+    files: dict[str, str]
+    symbols: list[IndexSymbol]
+    ports: list[Port]
+    facts: list[IndexFact]
+    diagnostics: list[str] = Field(default_factory=list)
+    cache_hits: int = 0
+
+
+class Gap(StrictModel):
+    code: str
+    message: str
+    evidence: list[EvidenceRef] = Field(default_factory=list)
+    after_port: str | None = None
+    before_port: str | None = None
+
+
+class VerificationResult(StrictModel):
+    status: ClaimStatus
+    verifier_version: str = "2"
+    evidence: list[EvidenceRef] = Field(default_factory=list)
+    gaps: list[Gap] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def source_proof_requires_evidence(self):
+        if self.status == "verified_source" and (
+            not self.evidence
+            or self.gaps
+            or any(ev.evidence_type != "source" for ev in self.evidence)
+        ):
+            raise ValueError("Source verification requires source evidence and no gaps")
+        return self
+
+
+class CandidateClaim(StrictModel):
+    claim_id: str
+    task_id: str
+    kind: Literal["asset", "relationship", "flow"]
+    fact_id: str
+    source: str
+    target: str
+    transform: Transform | None = None
+    guard: str | None = None
+    attributes: dict[str, Any] = Field(default_factory=dict)
+    evidence: list[EvidenceRef] = Field(min_length=1)
+    status: Literal["proposed"] = "proposed"
+
+
+class FlowHop(StrictModel):
+    hop_id: str
+    origin_port: str
+    target_port: str
+    transform: Transform
+    guard: str | None = None
+    verification: VerificationResult
+
+
+class FlowPath(StrictModel):
+    flow_path_id: str
+    origin_port: str
+    sink_port: str
+    labels: list[str] = Field(default_factory=list)
+    hops: list[FlowHop]
+    status: ClaimStatus
+    gaps: list[Gap] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def check_complete_path(self):
+        continuous = bool(self.hops) and self.hops[0].origin_port == self.origin_port
+        continuous = continuous and self.hops[-1].target_port == self.sink_port
+        continuous = continuous and all(
+            left.target_port == right.origin_port
+            for left, right in zip(self.hops, self.hops[1:], strict=False)
+        )
+        if self.status == "verified_source" and (
+            not continuous
+            or self.gaps
+            or any(h.verification.status != "verified_source" for h in self.hops)
+        ):
+            raise ValueError("A verified path requires a continuous, fully verified chain")
+        if self.status in {"partial", "unresolved"} and not self.gaps:
+            raise ValueError("An incomplete path requires a named gap")
+        return self
+
+
+class Budget(StrictModel):
+    max_steps: int = Field(default=12, ge=0)
+    max_tokens: int = Field(default=250000, ge=0)
+    max_seconds: float = Field(default=600, ge=0)
+
+
+class InvestigationTask(StrictModel):
+    task_id: str
+    repository_id: str
+    commit_sha: str
+    task_type: Literal["asset", "relationship", "flow"]
+    objective: str
+    anchors: list[str] = Field(default_factory=list)
+    relevant_files: list[str] = Field(default_factory=list)
+    hypothesis: str | None = None
+    stopping_condition: str = "Verified adjacent claims, explicit abstention, or budget exhaustion"
+    allowed_tools: list[str] = Field(
+        default_factory=lambda: [
+            "repo_map",
+            "find_symbols",
+            "find_references",
+            "read_symbol",
+            "read_source_window",
+            "find_registrations",
+            "get_flow_slice",
+            "submit_claim",
+        ]
+    )
+    budget: Budget = Field(default_factory=Budget)
+    steps: int = 0
+    tokens: int = 0
+    elapsed_seconds: float = 0
+    failed_verifications: int = 0
+    status: Literal["pending", "running", "complete", "budget_exhausted", "unresolved"] = "pending"
+    claims: list[CandidateClaim] = Field(default_factory=list)
+    results: list[VerificationResult] = Field(default_factory=list)
+    gaps: list[Gap] = Field(default_factory=list)
+    model_events: list[dict[str, Any]] = Field(default_factory=list)
+    context: dict[str, Any] = Field(default_factory=dict)
+    routing_hints: dict[str, Any] = Field(default_factory=dict)
+
+
+class EvidenceGraph(StrictModel):
+    schema_version: Literal[2] = 2
+    repository_id: str
+    commit_sha: str
+    graph_version_id: str
+    ports: list[Port]
+    assets: list[CandidateClaim]
+    relationships: list[CandidateClaim]
+    verifications: dict[str, VerificationResult]
+    hops: list[FlowHop]
+    paths: list[FlowPath]
+    gaps: list[Gap]
+    tasks: list[InvestigationTask] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def check_links(self):
+        ids = [p.port_id for p in self.ports]
+        if len(ids) != len(set(ids)):
+            raise ValueError("Duplicate port IDs")
+        for hop in self.hops:
+            if hop.origin_port not in ids or hop.target_port not in ids:
+                raise ValueError("Unknown hop port")
+        for claim in [*self.assets, *self.relationships]:
+            if claim.claim_id not in self.verifications:
+                raise ValueError("Missing claim verification")
+        for ev in [p.evidence for p in self.ports]:
+            if (ev.repository_id, ev.commit_sha) != (self.repository_id, self.commit_sha):
+                raise ValueError("Port belongs to another source revision")
+        known_hops = {hop.hop_id: hop for hop in self.hops}
+        for path in self.paths:
+            if any(known_hops.get(hop.hop_id) != hop for hop in path.hops):
+                raise ValueError("Path references an absent or altered hop")
+        return self

runtime_labs_contracts-0.1.0/src/messaging.py

@@ -0,0 +1,341 @@
+"""Scan-completed events and the publish/subscribe transport that carries them.
+
+The scanner publishes to one topic after its artifacts are on disk. The message
+is a claim check: it names the scanner's output files (``assets.json`` and the
+deployment manifest) rather than embedding them, so the topic stays small and the
+immutable artifacts remain the source of truth.
+Consumers pull from their own subscription, so several pipelines can read the
+same topic independently.
+"""
+
+import os
+import queue
+import sqlite3
+import threading
+import time
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Callable, Protocol
+
+from contracts import StrictModel
+from pydantic import Field
+
+SCAN_COMPLETED_TOPIC = "runtime-labs-scan-completed"
+PIPELINE_SUBSCRIPTION = "data-processing-pipelines"
+SPANS_INGESTED_TOPIC = "runtime-labs-spans-ingested"
+CORRELATION_SUBSCRIPTION = "data-processing-pipelines-correlation"
+CORRELATION_PREFIX = "runtime_labs.ctx."
+
+
+class ScanCompleted(StrictModel):
+    event_id: str = Field(min_length=1)
+    workspace_repository_id: str = Field(min_length=1)
+    scan_id: str = Field(min_length=1)
+    source_repository_id: str
+    commit_sha: str
+    assets_path: str  # the scanner's asset graph; consumers never read source
+    manifest_path: str
+    published_at: str = Field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+
+
+class IngestedSpan(StrictModel):
+    """A span as the pipelines receive it: the raw span plus the facts they correlate on."""
+
+    trace_id: str
+    span_id: str
+    parent_span_id: str | None = None
+    start_time_ns: int | None = None
+    end_time_ns: int | None = None
+    node_id: str | None = None
+    # The stored span as received, so the pipelines can build trace views from it.
+    payload: dict | None = None
+    # Raw ``runtime_labs.ctx.*`` attributes without the prefix, e.g.
+    # {"langgraph.thread_id": "conv-42"}. Never interpreted by the SDK or the API.
+    identifiers: dict[str, str] = Field(default_factory=dict)
+
+
+class SpansIngested(StrictModel):
+    event_id: str = Field(min_length=1)
+    workspace_repository_id: str = Field(min_length=1)
+    spans: list[IngestedSpan] = Field(min_length=1)
+    published_at: str = Field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+
+    @classmethod
+    def from_spans(cls, event_id, workspace_repository_id, spans):
+        """Build from stored span dicts (trace_id, span_id, attributes, ...)."""
+        facts = []
+        for span in spans:
+            attributes = span.get("attributes") or {}
+            facts.append(
+                IngestedSpan(
+                    trace_id=span["trace_id"],
+                    span_id=span["span_id"],
+                    parent_span_id=span.get("parent_span_id"),
+                    start_time_ns=span.get("start_time_ns"),
+                    end_time_ns=span.get("end_time_ns"),
+                    node_id=attributes.get("runtime_labs.node_id"),
+                    payload=span,
+                    identifiers={
+                        key.removeprefix(CORRELATION_PREFIX): str(value)
+                        for key, value in attributes.items()
+                        if key.startswith(CORRELATION_PREFIX) and value not in (None, "")
+                    },
+                )
+            )
+        return cls(event_id=event_id, workspace_repository_id=workspace_repository_id, spans=facts)
+
+
+@dataclass
+class Received:
+    """One delivered message. Ack removes it; nack makes it deliverable again."""
+
+    data: bytes
+    ack: Callable[[], None]
+    nack: Callable[[], None]
+
+
+class Broker(Protocol):
+    def ensure(self, topic: str, subscription: str | None = None) -> None: ...
+
+    def publish(self, topic: str, data: bytes) -> None: ...
+
+    def pull(
+        self, subscription: str, *, max_messages: int = 10, timeout: float = 5.0
+    ) -> list[Received]: ...
+
+
+class MemoryBroker:
+    """Process-local broker with fan-out per subscription, for tests and demos."""
+
+    def __init__(self):
+        self._topics: dict[str, list[str]] = {}
+        self._queues: dict[str, queue.Queue] = {}
+        self._lock = threading.Lock()
+
+    def ensure(self, topic, subscription=None):
+        with self._lock:
+            subscriptions = self._topics.setdefault(topic, [])
+            if subscription and subscription not in subscriptions:
+                subscriptions.append(subscription)
+                self._queues[subscription] = queue.Queue()
+
+    def publish(self, topic, data):
+        with self._lock:
+            if topic not in self._topics:
+                raise KeyError(f"Unknown topic {topic}")
+            targets = [self._queues[name] for name in self._topics[topic]]
+        for target in targets:
+            target.put(data)
+
+    def pull(self, subscription, *, max_messages=10, timeout=5.0):
+        source = self._queues[subscription]
+        received = []
+        try:
+            while len(received) < max_messages:
+                data = source.get(timeout=timeout if not received else 0)
+                received.append(
+                    Received(data, ack=lambda: None, nack=lambda data=data: source.put(data))
+                )
+        except queue.Empty:
+            pass
+        return received
+
+
+class PubSubBroker:
+    """Google Cloud Pub/Sub. ``PUBSUB_EMULATOR_HOST`` selects the local emulator."""
+
+    def __init__(self, project: str | None = None):
+        from google.cloud import pubsub_v1
+
+        self.project = (
+            project
+            or os.environ.get("RUNTIME_LABS_PUBSUB_PROJECT")
+            or os.environ.get("GOOGLE_CLOUD_PROJECT")
+            or "runtime-labs-local"
+        )
+        self._publisher = pubsub_v1.PublisherClient()
+        self._subscriber = pubsub_v1.SubscriberClient()
+
+    def _topic(self, topic):
+        return self._publisher.topic_path(self.project, topic)
+
+    def _subscription(self, subscription):
+        return self._subscriber.subscription_path(self.project, subscription)
+
+    def ensure(self, topic, subscription=None):
+        from google.api_core.exceptions import AlreadyExists
+
+        try:
+            self._publisher.create_topic(request={"name": self._topic(topic)})
+        except AlreadyExists:
+            pass
+        if subscription:
+            try:
+                self._subscriber.create_subscription(
+                    request={
+                        "name": self._subscription(subscription),
+                        "topic": self._topic(topic),
+                        "ack_deadline_seconds": 60,
+                    }
+                )
+            except AlreadyExists:
+                pass
+
+    def publish(self, topic, data):
+        self._publisher.publish(self._topic(topic), data).result(timeout=30)
+
+    def pull(self, subscription, *, max_messages=10, timeout=5.0):
+        from google.api_core.exceptions import DeadlineExceeded
+
+        name = self._subscription(subscription)
+        try:
+            response = self._subscriber.pull(
+                request={"subscription": name, "max_messages": max_messages},
+                timeout=timeout,
+            )
+        except DeadlineExceeded:
+            return []
+
+        def ack(ack_id):
+            self._subscriber.acknowledge(request={"subscription": name, "ack_ids": [ack_id]})
+
+        def nack(ack_id):
+            self._subscriber.modify_ack_deadline(
+                request={"subscription": name, "ack_ids": [ack_id], "ack_deadline_seconds": 0}
+            )
+
+        return [
+            Received(
+                m.message.data,
+                ack=lambda i=m.ack_id: ack(i),
+                nack=lambda i=m.ack_id: nack(i),
+            )
+            for m in response.received_messages
+        ]
+
+
+class LocalBroker:
+    """Durable broker in one SQLite file, safe across processes. No services to run.
+
+    Same semantics as the topic/subscription model: every subscription that exists
+    when a message is published gets its own copy; unacked messages are redelivered
+    once their lease expires.
+    """
+
+    LEASE_SECONDS = 60
+
+    def __init__(self, path):
+        self.path = str(path)
+        Path(self.path).parent.mkdir(parents=True, exist_ok=True)
+        with self._db() as db:
+            db.executescript(
+                """
+                PRAGMA journal_mode=WAL;
+                CREATE TABLE IF NOT EXISTS subscriptions (
+                  topic TEXT NOT NULL, name TEXT NOT NULL, PRIMARY KEY(topic, name));
+                CREATE TABLE IF NOT EXISTS topics (name TEXT PRIMARY KEY);
+                CREATE TABLE IF NOT EXISTS messages (
+                  id INTEGER PRIMARY KEY AUTOINCREMENT, subscription TEXT NOT NULL,
+                  data BLOB NOT NULL, leased_until REAL NOT NULL DEFAULT 0);
+                """
+            )
+
+    def _db(self):
+        db = sqlite3.connect(self.path, timeout=30)
+        return _Transaction(db)
+
+    def ensure(self, topic, subscription=None):
+        with self._db() as db:
+            db.execute("INSERT OR IGNORE INTO topics VALUES(?)", (topic,))
+            if subscription:
+                db.execute("INSERT OR IGNORE INTO subscriptions VALUES(?,?)", (topic, subscription))
+
+    def publish(self, topic, data):
+        with self._db() as db:
+            if not db.execute("SELECT 1 FROM topics WHERE name=?", (topic,)).fetchone():
+                raise KeyError(f"Unknown topic {topic}")
+            names = [
+                r[0] for r in db.execute("SELECT name FROM subscriptions WHERE topic=?", (topic,))
+            ]
+            db.executemany(
+                "INSERT INTO messages(subscription, data) VALUES(?,?)", [(n, data) for n in names]
+            )
+
+    def pull(self, subscription, *, max_messages=10, timeout=5.0):
+        deadline = time.monotonic() + timeout
+        while True:
+            now = time.time()
+            with self._db() as db:
+                rows = db.execute(
+                    "SELECT id, data FROM messages WHERE subscription=? AND leased_until<=? "
+                    "ORDER BY id LIMIT ?",
+                    (subscription, now, max_messages),
+                ).fetchall()
+                db.executemany(
+                    "UPDATE messages SET leased_until=? WHERE id=?",
+                    [(now + self.LEASE_SECONDS, r[0]) for r in rows],
+                )
+            if rows or time.monotonic() >= deadline:
+                break
+            time.sleep(0.25)
+
+        def ack(message_id):
+            with self._db() as db:
+                db.execute("DELETE FROM messages WHERE id=?", (message_id,))
+
+        def nack(message_id):
+            with self._db() as db:
+                db.execute("UPDATE messages SET leased_until=0 WHERE id=?", (message_id,))
+
+        return [
+            Received(data, ack=lambda i=i: ack(i), nack=lambda i=i: nack(i)) for i, data in rows
+        ]
+
+
+class _Transaction:
+    """Commit on success, always close (sqlite3's own context manager never closes)."""
+
+    def __init__(self, db):
+        self.db = db
+
+    def __enter__(self):
+        return self.db
+
+    def __exit__(self, exc_type, *_):
+        try:
+            self.db.rollback() if exc_type else self.db.commit()
+        finally:
+            self.db.close()
+
+
+def local_data_dir() -> Path:
+    return Path(os.environ.get("RUNTIME_LABS_DATA", ".runtime-labs")).resolve()
+
+
+_default_broker = None
+
+
+def broker_from_environment() -> Broker:
+    """Local SQLite queue by default; ``RUNTIME_LABS_BROKER=pubsub`` selects Pub/Sub
+    (the emulator when ``PUBSUB_EMULATOR_HOST`` is set). One broker per process."""
+    global _default_broker
+    if _default_broker is None:
+        if os.environ.get("RUNTIME_LABS_BROKER", "local") == "pubsub":
+            _default_broker = PubSubBroker()
+        else:
+            _default_broker = LocalBroker(local_data_dir() / "broker.db")
+    return _default_broker
+
+
+def publish_scan_completed(broker: Broker, event: ScanCompleted) -> None:
+    # A topic drops messages that arrive before any subscription exists, so the
+    # publisher provisions the pipeline's subscription and no scan is lost while
+    # the pipeline is down.
+    broker.ensure(SCAN_COMPLETED_TOPIC, PIPELINE_SUBSCRIPTION)
+    broker.publish(SCAN_COMPLETED_TOPIC, event.model_dump_json().encode())
+
+
+def publish_spans_ingested(broker: Broker, event: SpansIngested) -> None:
+    broker.ensure(SPANS_INGESTED_TOPIC, CORRELATION_SUBSCRIPTION)
+    broker.publish(SPANS_INGESTED_TOPIC, event.model_dump_json().encode())

runtime_labs_contracts-0.1.0/src/repository_identity.py

@@ -0,0 +1,63 @@
+"""Canonical Git repository identities shared by onboarding and SDK bootstrap."""
+
+import re
+import subprocess
+from pathlib import Path
+from urllib.parse import urlsplit
+
+
+def normalize_git_url(value: str) -> str:
+    value = value.strip()
+    if not value or any(c.isspace() for c in value):
+        raise ValueError("Invalid Git remote")
+    canonical_port = False
+    if "://" not in value and re.match(r"^[^/@:]+:[0-9]+/", value):
+        value = "ssh://" + value
+        canonical_port = True
+    if "://" not in value:
+        scp = re.fullmatch(r"(?:[^/@:]+@)?([^/:]+):(.+)", value)
+        value = f"ssh://{scp[1]}/{scp[2]}" if scp else "https://" + value
+    parsed = urlsplit(value)
+    if parsed.scheme not in {"https", "http", "ssh", "git"} or not parsed.hostname:
+        raise ValueError("Unsupported Git remote")
+    path = parsed.path.strip("/").removesuffix(".git")
+    parts = path.split("/")
+    if len(parts) < 2 or any(p in {"", ".", ".."} for p in parts):
+        raise ValueError("Git remote must include owner and repository")
+    host = parsed.hostname.lower()
+    if host == "github.com":
+        path = path.lower()
+    port = parsed.port
+    if port and (
+        canonical_port
+        or (parsed.scheme, port) not in {("ssh", 22), ("http", 80), ("https", 443), ("git", 9418)}
+    ):
+        host += f":{port}"
+    return f"{host}/{path}"
+
+
+def _git(directory, *args):
+    return subprocess.run(
+        ["git", "-C", str(directory), *args],
+        check=True,
+        capture_output=True,
+        text=True,
+        timeout=3,
+    ).stdout.strip()
+
+
+def git_identity(directory: Path) -> tuple[str, str | None]:
+    def git(*args):
+        return _git(directory, *args)
+
+    remote = normalize_git_url(git("config", "--get", "remote.origin.url"))
+    try:
+        commit = git("rev-parse", "HEAD")
+    except subprocess.SubprocessError:
+        commit = None
+    return remote, commit
+
+
+def git_subdirectory(directory: Path) -> str:
+    """Where ``directory`` sits inside its checkout: "" at the root, else "a/b"."""
+    return _git(directory, "rev-parse", "--show-prefix").strip("/")