symfonic.services.shadow.trust

trust

SHD-TR — extension trust classes.

The effect-port classification governs effects that cross framework ports. Preserved in-process Python tools, plugin callbacks, and contributed stages can open a socket without asking anybody, so classifying ports alone would let a shadow run claim suppression it never achieved. This registry closes that gap with a second axis: every registered tool, plugin, and contributed stage is either port-mediated (all of its effects cross classified ports) or opaque (unknown, therefore non-shadowable and non-replayable).

Three rules make the axis conservative rather than decorative:

1. The default is opaque. An extension nobody classified is opaque, and so is every adopter-registered extension until it is promoted deliberately.
2. Promotion requires a construction proof — injected framework port clients only, or framework-owned audited code — verified by somebody other than the extension itself. Self-declaration is refused by type.
3. Promotion requires a named human reviewer from the owning capability, and that approval is what the cutover evidence records.

ConstructionProof dataclass

ConstructionProof(method: ProofMethod, verified_by: str, injected_ports: frozenset[str] = frozenset(), audited_module: str = '', self_declared: bool = False)

Why this extension's effects cannot leave the classified ports.

ExtensionRecord dataclass

ExtensionRecord(extension_id: str, kind: ExtensionKind, origin: ExtensionOrigin, trust: TrustClass, reason: str, proof: ConstructionProof | None = None, approval: ReviewerApproval | None = None)

What the registry knows about one extension.

shadowable property

shadowable: bool

Opaque extensions are non-shadowable and non-replayable.

ExtensionTrustRegistry

ExtensionTrustRegistry(*, classified_ports: Iterable[str] = ())

Assigns and enforces trust classes. Default-deny by construction.

Source code in src/symfonic/services/shadow/trust.py

def __init__(self, *, classified_ports: Iterable[str] = ()) -> None:
    self._classified = frozenset(classified_ports)
    self._records: dict[str, ExtensionRecord] = {}
    self._demoted: dict[str, str] = {}

classify_port_mediated

classify_port_mediated(extension_id: str, kind: ExtensionKind, *, proof: ConstructionProof, approval: ReviewerApproval, origin: ExtensionOrigin = ExtensionOrigin.FRAMEWORK) -> ExtensionRecord

Promote to port-mediated. Refuses everything short of the bar.

Source code in src/symfonic/services/shadow/trust.py

def classify_port_mediated(
    self,
    extension_id: str,
    kind: ExtensionKind,
    *,
    proof: ConstructionProof,
    approval: ReviewerApproval,
    origin: ExtensionOrigin = ExtensionOrigin.FRAMEWORK,
) -> ExtensionRecord:
    """Promote to port-mediated. Refuses everything short of the bar."""
    if extension_id in self._demoted:
        raise TrustDeclarationError(
            f"{extension_id!r} was demoted to opaque "
            f"({self._demoted[extension_id]}); it cannot be re-promoted "
            "without a fresh construction proof under a new id"
        )
    self._require_independent_proof(extension_id, proof)
    self._require_construction(extension_id, proof)
    self._require_named_reviewer(extension_id, approval)
    record = ExtensionRecord(
        extension_id=extension_id,
        kind=kind,
        origin=origin,
        trust=TrustClass.PORT_MEDIATED,
        reason=f"{proof.method.value} verified by {proof.verified_by}",
        proof=proof,
        approval=approval,
    )
    self._records[extension_id] = record
    return record

demote

demote(extension_id: str, reason: str) -> ExtensionRecord

Force an extension to opaque and bar re-promotion under this id.

Source code in src/symfonic/services/shadow/trust.py

def demote(self, extension_id: str, reason: str) -> ExtensionRecord:
    """Force an extension to opaque and bar re-promotion under this id."""
    previous = self.record_of(extension_id)
    record = ExtensionRecord(
        extension_id=extension_id,
        kind=previous.kind,
        origin=previous.origin,
        trust=TrustClass.OPAQUE,
        reason=reason,
        proof=previous.proof,
        approval=previous.approval,
    )
    self._records[extension_id] = record
    self._demoted[extension_id] = reason
    return record

record_of

record_of(extension_id: str) -> ExtensionRecord

The record, or a synthesized opaque one. Never raises for unknown.

Source code in src/symfonic/services/shadow/trust.py

def record_of(self, extension_id: str) -> ExtensionRecord:
    """The record, or a synthesized opaque one. Never raises for unknown."""
    known = self._records.get(extension_id)
    if known is not None:
        return known
    return ExtensionRecord(
        extension_id=extension_id,
        kind=ExtensionKind.TOOL,
        origin=ExtensionOrigin.ADOPTER,
        trust=TrustClass.OPAQUE,
        reason="unregistered extension defaults to opaque",
    )

register

register(extension_id: str, kind: ExtensionKind, *, origin: ExtensionOrigin = ExtensionOrigin.ADOPTER, reason: str = 'registered without a construction proof') -> ExtensionRecord

Register an extension as opaque. This is the only bulk entry point.

Source code in src/symfonic/services/shadow/trust.py

def register(
    self,
    extension_id: str,
    kind: ExtensionKind,
    *,
    origin: ExtensionOrigin = ExtensionOrigin.ADOPTER,
    reason: str = "registered without a construction proof",
) -> ExtensionRecord:
    """Register an extension as opaque. This is the only bulk entry point."""
    record = ExtensionRecord(
        extension_id=extension_id,
        kind=kind,
        origin=origin,
        trust=TrustClass.OPAQUE,
        reason=reason,
    )
    self._records[extension_id] = record
    return record

ProofMethod

Bases: StrEnum

The only two ways an extension can be port-mediated by construction.

ReviewerApproval dataclass

ReviewerApproval(reviewer: str, capability: str, approved_at: str, statement: str = '')

A named human from the owning capability signing off on a promotion.