> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qwedai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage examples

> QWED-Infra code examples for parsing Terraform, verifying IAM with Z3, cloud cost budgets, network reachability, and release boundary checks.

## 1. Parsing Terraform

```python theme={null}
from qwed_infra import TerraformParser

parser = TerraformParser()
resources = parser.parse_directory("./terraform/prod")

# Returns normalized resources:
# {
#   "policies": [...],
#   "instances": [...],
#   "subnets": [...],
#   "route_tables": [...],
#   "security_groups": {...},
#   ...
# }
```

## 2. IAM Policy Verification (Z3)

```python theme={null}
from qwed_infra import IamGuard

guard = IamGuard()

# policy comes from parsed Terraform resources (see Example 1)
policy = resources["policies"][0]

# Context-aware access check
result = guard.verify_access(
    policy,
    action="s3:GetObject",
    resource="arn:aws:s3:::bucket/*",
    context={"aws:SourceIp": "192.168.1.5"},
)
print(f"Allowed? {result.allowed}")   # True/False
print(f"Verified? {result.verified}") # True/False
print(f"Proof: {result.proof}")       # Z3 proof string

# Least-privilege check
result = guard.verify_least_privilege(policy)
print(f"Over-privileged? {result.allowed}")
```

## 3. Cloud Cost Budget Enforcement

```python theme={null}
from qwed_infra import CostGuard

cost = CostGuard()

resources = {
    "instances": [
        {"id": "web-cluster", "instance_type": "t3.micro", "count": 2},
        {"id": "gpu-trainer", "instance_type": "p4d.24xlarge", "count": 1},
    ]
}

result = cost.verify_budget(resources, budget_monthly=500.0)

print(f"Within Budget? {result.within_budget}")  # False
print(f"Total: ${result.total_monthly_cost}")     # ~23905.36
print(f"Reason: {result.reason}")
```

## 4. Network Reachability

```python theme={null}
from qwed_infra import NetworkGuard

net = NetworkGuard()

infra = {
    "subnets": [
        {"id": "public-subnet", "security_groups": ["sg-web"]}
    ],
    "route_tables": [
        {"subnet_id": "public-subnet", "routes": {"0.0.0.0/0": "igw-main"}}
    ],
    "security_groups": {
        "sg-web": {"ingress": [{"port": 80, "cidr": "0.0.0.0/0"}]}
    },
}

# Is port 80 accessible from the internet?
res = net.verify_reachability(infra, "internet", "public-subnet", 80)
print(f"Reachable? {res.reachable}")  # True
print(f"Path: {res.path}")           # ['internet', 'igw-main', ...]
```

## 5. Release Boundary Verification

```python theme={null}
from pathlib import Path
from qwed_infra import ArtifactBoundaryGuard

guard = ArtifactBoundaryGuard()

result = guard.verify_package_boundary(
    package_dir=Path("./src/qwed_infra"),
    pyproject_path=Path("./pyproject.toml"),
    package_name="qwed_infra",
)

print(f"Safe to publish? {result.is_safe}")
print(f"Findings: {len(result.findings)}")
for f in result.findings:
    print(f"  [{f.severity}] {f.finding_type}: {f.file_path} — {f.reason}")
```

## 6. Converting Results to Diagnostics

Every guard exposes a `to_diagnostic()` method that converts its native result into a unified `InfraDiagnosticResult`:

```python theme={null}
# From IamGuard
diag = IamGuard.to_diagnostic(result)  # returns InfraDiagnosticResult

print(f"Status: {diag.status.value}")         # VERIFIED / UNVERIFIABLE / BLOCKED
print(f"Agent: {diag.agent_message}")          # Layer 1
print(f"Constraint: {diag.constraint_id}")     # Layer 2 field
print(f"Authoritative: {diag.is_authoritative}")  # True iff proof_ref is set
print(f"Proof: {diag.proof_ref}")              # Layer 3 — sha256:... or None

# Serialize for audit logging
payload = diag.to_dict()

# Deserialize back
from qwed_infra.diagnostics import InfraDiagnosticResult
restored = InfraDiagnosticResult.from_dict(payload)
```

## 7. Working with Audit Traces

```python theme={null}
from qwed_infra.audit import (
    IAM_DENY_PRECEDENCE,
    NETWORK_REACHABILITY,
    COST_WITHIN_BUDGET,
    ARTIFACT_BOUNDARY_VERIFIED,
    build_trace,
    trace_proof_ref,
)

# Build a structured audit trace
trace = build_trace(
    IAM_DENY_PRECEDENCE,
    outcome="ALLOWED",
    inputs={"action": "s3:GetObject", "resource": "arn:aws:s3:::bucket/*"},
)
# trace = {
#     "rule_id": "IAM_DENY_PRECEDENCE",
#     "statute": "AWS IAM Evaluation Logic (deny precedence)",
#     "jurisdiction": "GENERIC",
#     "outcome": "ALLOWED",
#     "inputs": {"action": "s3:GetObject", "resource": "..."},
# }

# Compute proof reference from a trace
ref = trace_proof_ref(trace)
print(ref)  # sha256:abc123...
```