Policy, verification, and learning

Propose allowlisted actions under default-deny policy, record explicit verification outcomes, and promote only confirmed truth into memory.

PHASE 1 · PRE-1.0PYTHON 3.11+EDIT ON GITHUB ↗

Proposal-only governance

Build PlaybookDocument and PolicyDocument values from lumis_sdk.domain, then compose them with ProposalService. The service validates the requested action against the playbook, evaluates the policy (unknown actions and missing rules fail closed), checks evidence provenance, and bounds typed parameters. The proposal pins document revisions, links to the diagnosis by digest, and expires:

python

from datetime import UTC, datetime, timedelta

from lumis_sdk.application import ProposalService
from lumis_sdk.domain import (
    DocumentMetadata,
    EvidenceReference,
    ParameterDefinition,
    ParameterType,
    PlaybookAction,
    PlaybookDocument,
    PolicyDocument,
    PolicyRule,
    RiskLevel,
)

playbook = PlaybookDocument(
    metadata=DocumentMetadata(name="worker-recovery", version="1"),
    actions=[
        PlaybookAction(
            name="restart",
            summary="Recommend a bounded worker restart.",
            risk=RiskLevel.HIGH,
            parameters=[
                ParameterDefinition(
                    name="replicas",
                    type=ParameterType.INTEGER,
                    minimum=1,
                    maximum=5,
                )
            ],
        )
    ],
)
policy = PolicyDocument(
    metadata=DocumentMetadata(name="production-policy", version="4"),
    rules=[
        PolicyRule(
            playbook_name="worker-recovery",
            action_name="restart",
            approval_required=True,
        )
    ],
)

now = datetime.now(UTC)
proposal = ProposalService(playbook, policy).propose(
    proposal_id="proposal-123",
    diagnosis_id="diagnosis-123",
    diagnosis_digest="a" * 64,
    evidence=[EvidenceReference(id="log-1", source="collector", digest="b" * 64)],
    action_name="restart",
    parameters={"replicas": 2},
    created_at=now,
    expires_at=now + timedelta(minutes=15),
)
assert proposal.execution_allowed is False

ApprovalLedger is a small reference implementation of decision idempotency. Production applications should persist ApprovalDecisionRecord values in their own auditable store. Checked schemas exist for playbook, policy, and proposal documents.

Verification-aware learning

Use VerificationRequest, VerificationRecord, and VerificationCheck for exchange and persistence. learn_from_verification applies conservative promotion rules to a MemoryStore: a passed result requires an explicit ConfirmedResolution with verified=True, truth_state=VERIFICATION_CONFIRMED, and the matching verification_id. Failed results become rejected memory. Unknown and timed-out results remain unconfirmed and require escalation—they never report recovery and never become reusable.

Replay evaluation

lumis_sdk.evaluation.evaluate_replay accepts ReplayCase values and returns exact deterministic counts, so rule and policy changes can be validated against a versioned corpus before they ship. Keep corpora synthetic or public, version them with the application, and report the methodology with the results.