spanforge.core.compliance_mapping

Programmatic compliance testing via the public spanforge.compliance facade: v1.0 compatibility checks, audit chain integrity verification, and multi-tenant isolation testing.

All compliance functions can be called directly without pytest.

See the Compliance User Guide for usage examples.

Compatibility checker

CompatibilityViolation

@dataclass(frozen=True)
class CompatibilityViolation:
    check_id: str
    rule: str
    detail: str
    event_id: str

A single compliance non-conformance found during a check.

Attributes:

CompatibilityResult

@dataclass
class CompatibilityResult:
    passed: bool
    events_checked: int
    violations: List[CompatibilityViolation]

Result of a compatibility compliance check across a batch of events.

Evaluates as True in a boolean context only when passed=True.

Attributes:

test_compatibility(events: Sequence[Event]) -> CompatibilityResult

Apply the spanforge v1.0 compatibility checklist to events.

Checks performed:

Args:

Returns: CompatibilityResult

Example:

from spanforge.compliance import test_compatibility

result = test_compatibility(my_events)
if not result:
    for v in result.violations:
        print(f"[{v.check_id}] {v.rule}: {v.detail}")

Audit chain integrity

ChainIntegrityViolation

A single chain integrity violation (broken prev_id link, tampered signature, or non-monotonic timestamp).

ChainIntegrityResult

Result of verify_chain_integrity(). Evaluates as True only when no violations were found.

Attributes: passed, chain_result, violations, events_verified, gaps_detected.

verify_chain_integrity(events: Sequence[Event], org_secret: str, *, check_monotonic_timestamps: bool = True) -> ChainIntegrityResult

Verify the structural integrity of an ordered event chain.

Checks:

• Each event's prev_id points to the preceding event's event_id.
• Timestamps are monotonically non-decreasing.
• No gaps in the chain.

Args:

Returns: ChainIntegrityResult

Multi-tenant isolation

IsolationViolation

A single isolation violation found during tenant boundary checking.

IsolationResult

Result of verify_tenant_isolation() or verify_events_scoped(). Evaluates as True only when no violations were found.

Attributes: passed, violations.

verify_tenant_isolation(group_a: Sequence[Event], group_b: Sequence[Event], *, strict: bool = False) -> IsolationResult

Verify that events from two tenant groups do not share org_id values.

Args:

Returns: IsolationResult

verify_events_scoped(events: Sequence[Event], *, expected_org_id: str | None = None, expected_team_id: str | None = None) -> IsolationResult

Verify that all events in events carry the expected scope values.

Useful for asserting that a batch of events belongs to a single organisation or team.

Args:

Returns: IsolationResult

Compliance Mapping Engine

ComplianceMappingEngine

Maps spanforge telemetry events to regulatory framework clauses and generates evidence packages with gap analysis and HMAC-signed attestations.

from spanforge.compliance import ComplianceMappingEngine

engine = ComplianceMappingEngine()

ComplianceAttestation

@dataclass
class ComplianceAttestation:
    model_id: str
    framework: str
    from_date: str
    to_date: str
    total_events: int
    clauses_covered: int
    clauses_total: int
    coverage_pct: float
    gaps: list[str]
    attestation_id: str
    timestamp: str
    signature: str
    model_owner: str | None
    model_risk_tier: str | None
    model_status: str | None
    model_warnings: list[str]
    explanation_coverage_pct: float | None

Key attributes:

generate_evidence_package(model_id, framework, from_date, to_date, audit_events=None) -> ComplianceEvidencePackage

Generate a complete evidence package for a regulatory framework.

Args:

Returns: ComplianceEvidencePackage — contains framework, model_id, mappings, gap_report, and attestation.

Clause-to-event-prefix mapping