Enforcement Layer

ACCESS_MATRIX = {
    "full": {
        "sections": ["*"],
        "can_approve_changes": True,
    },
    "schedule+meds": {
        "sections": [
            "members", "care_recipient", "schedule", "medications",
            "appointments", "availability", "active_issues",
        ],
        "can_approve_changes": False,
    },
    "schedule": {
        "sections": [
            "members", "schedule", "availability", "active_issues",
        ],
        "can_approve_changes": False,
    },
    "provider": {
        "sections": [
            "care_recipient", "medications", "appointments", "members",
        ],
        "can_approve_changes": False,
    },
    "limited": {
        "sections": ["members", "care_recipient"],
        "can_approve_changes": False,
    },
}

def filter_family_context(family_md: str, access_level: str) -> str

def check_outbound_message(
    message: str,
    access_level: str
) -> LeakageResult

def get_filtered_sections(access_level: str) -> list[str]

def can_approve(access_level: str) -> bool

from enforcement.phi_audit import PHIAuditLogger

audit = PHIAuditLogger(log_dir=paths.logs)

audit.log_context_load(
    family_id: str,
    accessor_phone: str,
    accessor_role: str,
    access_level: str,
    sections_loaded: list[str],
    trigger_message: str
)

audit.log_response_sent(
    family_id: str,
    recipient_phone: str,
    recipient_role: str,
    access_level: str,
    response_length: int,
    leakage_clean: bool
)

audit.log_response_blocked(
    family_id: str,
    recipient_phone: str,
    access_level: str,
    leaked_categories: list[str],
    leaked_terms: list[str]
)

audit.log_unknown_number(phone: str)

{
  "timestamp": "2026-02-28T14:32:01.123456Z",
  "event": "context_load",
  "family_id": "kano",
  "accessor": {
    "phone": "+16517037981",
    "role": "family_caregiver",
    "access_level": "schedule"
  },
  "sections_loaded": ["members", "schedule", "availability", "active_issues"],
  "trigger": "Can someone take auntie to work tomorrow at 8am?"
}

def apply_updates(
    family_md_path: Path,
    updates: list[FileUpdate],
    backup_dir: Path | None = None,
) -> EditResult

@dataclass
class FileUpdate:
    section: str       # Section key (e.g., "schedule", "medications")
    operation: str     # "append" | "prepend" | "replace" | "resolve_issue"
    content: str       # Text to add or replacement content
    old_content: str   # For "replace" — the text being replaced

FileUpdate(
    section="schedule",
    operation="append",
    content="- 2026-03-01 08:00: Doctor appointment (Marcus driving)",
    old_content=""
)

FileUpdate(
    section="active_issues",
    operation="prepend",
    content="- [ ] Follow up with pharmacy about refill",
    old_content=""
)

FileUpdate(
    section="medications",
    operation="replace",
    content="- Lisinopril 10mg — 1x daily at 8am",
    old_content="- Lisinopril 5mg — 1x daily at 8am"
)

FileUpdate(
    section="active_issues",
    operation="resolve_issue",
    content="pharmacy refill",
    old_content=""
)

SECTION_FILE_MAP = {
    "schedule": "schedule.md",
    "this_week": "schedule.md",
    "medications": "medications.md",
    "active_medications": "medications.md",
    "medication_hold_log": "medications.md",
}

def resolve_target_file(family_dir: Path, section_key: str) -> Path

def validate_family_file(content: str) -> tuple[bool, list[str]]

APPROVAL_REQUIRED = {
    ("medications", "append"),
    ("medications", "prepend"),
    ("medications", "replace"),
    ("care_recipient", "replace"),
    ("members", "append"),
    ("members", "replace"),
}

def classify_updates(updates: list[FileUpdate]) -> ClassifiedUpdates

def create_pending(
    family_dir: Path,
    update: FileUpdate,
    description: str,
    requester_phone: str,
    requester_name: str,
    approver_phones: list[str],
    expiry_hours: int = 24,
) -> PendingApproval

def resolve_approval(
    family_dir: Path,
    approval_id: str,
    approved: bool,
    by_phone: str,
) -> dict

def detect_approval_response(message: str) -> tuple[bool | None, str | None]

def format_confirmation_sms(approval: PendingApproval) -> str

⚠️ Approval needed: {description}
Requested by {requester_name}.
Reply YES or NO (ref: {approval_id})

def expire_stale(family_dir: Path) -> int

# 1. Pre-filter context
filtered_context = filter_family_context(raw_context, access_level)

# 2. Log PHI access
audit.log_context_load(family_id, phone, role, access_level, sections, body)

# 3. Generate response
result = await generate_response(system_context, body)

# 4. Post-check for leakage
leakage = check_outbound_message(result["sms_response"], access_level)

if not leakage.is_clean:
    audit.log_response_blocked(family_id, phone, access_level, leakage.leaked_categories, leakage.leaked_terms)
    return BLOCKED_RESPONSE

# 5. Classify and apply updates
classified = classify_updates(parse_update_instructions(result["family_file_updates"]))
edit_result = apply_updates(family_md_path, classified.auto_apply)

# 6. Create pending approvals for high-risk changes
for update, reason in classified.needs_approval:
    create_pending(family_dir, update, reason, phone, name, approver_phones)