Memory
# DocuClear Compliance Engine — Target Compliance Schema ## Three-Layer State Model (KEY CORRECTION over earlier research draft) - **Reference business facts**: Stable facts about the assessed business - **Normative knowledge**: Canonical legal/policy knowledge used by the engine - **Runtime assessment state**: Time-bound outputs of evaluating one business against one rule/version set This fixes ambiguities where ClassificationOutcome and EvidenceArtifact were mistakenly used as both canonical concepts and runtime records. ## Core Evaluation Path Organisation → Business Area → Use Case → Role → Classification Result → Obligation Applicability → Evidence Submission → Assessment Finding AI-specific compliance is primarily driven by **use cases**, not the organisation in abstract. ## Reference Business Facts Entities | Entity | Key fields | |---|---| | `Organisation` | organisation_id, name, jurisdictions, sector, employee_band | | `BusinessArea` | business_area_id, organisation_id, name, area_type | | `UseCase` | use_case_id, business_area_id, name, description, purpose (FIRST-CLASS, do not collapse) | | `Tool` | tool_id, name, vendor_id, tool_category | | `Vendor` | vendor_id, name, hq_jurisdiction | | `Model` | model_id, name, model_type | ## Normative Knowledge Entities (live in SurrealDB) | Entity | Key fields | |---|---| | `Regime` | regime_id, name, jurisdiction, source_url, effective_date — e.g. EU-AI-ACT, UK-GDPR, DUAA, ICO-AI-GUIDANCE | | `LegalProvision` | provision_id, regime_id, source_ref, title, effective_from | | `RoleType` | role_type_id, label, definition, source_ref — Provider, Deployer, Controller, Processor, Employer | | `ClassificationScheme` | scheme_id, regime_id, name, scope (NOT canonical outcomes themselves) | | `DecisionRule` | decision_rule_id, regime_id, rule_kind, target_level, version | | `RuleCondition` | rule_condition_id, decision_rule_id, lhs_path, operator, rhs_value | | `Question` | question_id, scheme_id, text, order_index | | `QuestionOutcomeMap` | map_id, question_id, answer_value, outcome_type, outcome_ref | | `Obligation` | obligation_id, regime_id, statement, category, applies_at_level | | `ControlRequirement` | control_requirement_id, obligation_id, description, control_type | | `EvidenceRequirement` | evidence_requirement_id, control_requirement_id, artifact_type, description | | `InteractionLink` | interaction_link_id, from_ref, to_ref, interaction_type (overlaps/amplifies/supersedes/shared_evidence) | ## Runtime Assessment State Entities (time-bound, not canonical) | Entity | Key fields | |---|---| | `AssessmentRun` | assessment_run_id, organisation_id, started_at, rule_bundle_version | | `RoleAssignment` | role_assignment_id, assessment_run_id, use_case_id, role_type_id, organisation_id | | `ClassificationResult` | classification_result_id, assessment_run_id, use_case_id, scheme_id, label | | `ApplicableObligation` | applicable_obligation_id, assessment_run_id, obligation_id, target_ref, trigger_ref | | `EvidenceSubmission` | evidence_submission_id, assessment_run_id, evidence_requirement_id, storage_url | | `AssessmentFinding` | finding_id, assessment_run_id, applicable_obligation_id, status (met/partial/not_met/not_tested) | | `Gap` | gap_id, finding_id, severity, summary | | `Recommendation` | recommendation_id, gap_id, text, priority | ## Core Graph Relationships Organisation HAS_AREA BusinessArea → HAS_USE_CASE UseCase → USES_TOOL Tool → SUPPLIED_BY Vendor / RUNS_MODEL Model Regime CONTAINS_PROVISION LegalProvision / HAS_CLASSIFICATION_SCHEME ClassificationScheme ClassificationScheme HAS_QUESTION Question / HAS_DECISION_RULE DecisionRule DecisionRule HAS_CONDITION RuleCondition / YIELDS_OBLIGATION Obligation / YIELDS_CLASSIFICATION label LegalProvision IMPLIES_OBLIGATION Obligation Obligation REQUIRES_CONTROL ControlRequirement → REQUIRES_EVIDENCE_TYPE EvidenceRequirement AssessmentRun ASSIGNS_ROLE RoleAssignment / GENERATES_CLASSIFICATION ClassificationResult / APPLIES_OBLIGATION ApplicableObligation ApplicableObligation HAS_FINDING AssessmentFinding EvidenceSubmission SUPPORTS_FINDING AssessmentFinding ## 8-Step Evaluation Order 1. Scope the organisation (applicable regimes from jurisdictions, sector, employee count, AI exposure) 2. Load business structure (areas, use cases, tools, models, vendors) 3. Assign roles per use case (provider/deployer/controller/processor/employer) 4. Classify each use case (run classification schemes and decision rules) 5. Derive applicable obligations (resolve which canonical obligations fire) 6. Generate evidence plan (expand to ControlRequirement and EvidenceRequirement) 7. Assess submissions and facts (create AssessmentFindings) 8. Aggregate gaps and recommendations ## Mapping from Existing Assets ### rules.json → target - framework → Regime.regime_id - article/source refs → LegalProvision - applies_when → DecisionRule + RuleCondition - recommended_actions → ControlRequirement templates - evidence_required → EvidenceRequirement templates - findings → Gap/finding text templates ### classification_tree.json → target - question_id → Question.question_id - step/step_name/order → ClassificationScheme + Question.order_index - text → Question.text - yes_outcome/no_outcome → QuestionOutcomeMap - obligation_codes → DecisionRule or classification-to-obligation link ### tools.json → target - name/category → Tool - vendor/vendor_hq → Vendor - trains_on_user_data, zero_retention_available, data_residency, gdpr_dpa_available → tool-level attributes for rules - risk_flags/data_tags → normalized tool risk facets feeding DecisionRule conditions ### Flow refactoring needed - Context Loader: expand to load use cases, tools, vendors, model facts - Rule Evaluator: split into role assignment, classification, obligation derivation, finding evaluation - Assessment Orchestrator: persist AssessmentRun, ClassificationResult, ApplicableObligation, AssessmentFinding (not flat blob) - Obligation Writer: write runtime ApplicableObligation records, NOT canonical obligation definitions ## Minimum Viable Blueprint Reference facts: Organisation, BusinessArea, UseCase, Tool, Vendor Normative: Regime, LegalProvision, RoleType, ClassificationScheme, DecisionRule, RuleCondition, Obligation, ControlRequirement, EvidenceRequirement, InteractionLink Runtime: AssessmentRun, RoleAssignment, ClassificationResult, ApplicableObligation, EvidenceSubmission, AssessmentFinding, Gap, Recommendation ## Recommended Next Actions 1. Freeze target schema as design baseline 2. Map every field from rules.json, classification_tree.json, tools.json, current flows into target entities 3. Define versioning policy for normative entities and runtime snapshots 4. Refactor orchestration into explicit phases: context load → role assignment → classification → obligation derivation → finding evaluation → reporting 5. Test against law-firm-with-AI-product scenario before broadening regime coverage
Tags: docuclear, schema, compliance-engine, surrealdb, entities, design, database, kind:semantic, status:canonical, project:docucleargraph, volatility:state, stale:as-of — Source: claude — 2026-07-02 15:59:27 UTC