Target Model

The target model classifies tools by their action type and computes the blast radius of proposed actions — what downstream systems, entities, and data will be affected if the action proceeds.

How It WorksCopy Anchor Link

Tool Classifier (tool_classifier.py)Copy Anchor Link

The ToolActionClassifier determines whether a tool call is a read (observation) or an action (mutation):

classifier = ToolActionClassifier(session)
is_action = classifier.classify("salesforce.update_contact", workspace_id)
# True = action (requires policy evaluation)
# False = read (pass-through)

Classification uses two strategies:

1. Explicit DB metadata — The praxom_tool_metadata table stores per-tool classifications set by administrators
2. Heuristic fallback — If no metadata exists, prefix-based heuristics classify tools (e.g., get_*, list_*, read_* = read; update_*, delete_*, create_* = action)

Results are cached per workspace with a configurable TTL.

Impact Engine (impact_engine.py)Copy Anchor Link

The PraxomImpactEngine computes blast radius for proposed actions:

engine = PraxomImpactEngine(session)
impact = engine.compute_impact(
    tool_name="salesforce.update_contact",
    arguments={"contact_id": "123"},
    workspace_id=workspace_id
)
# impact.affected_entities: list of AffectedEntity
# impact.compensation_plan: optional compensating-action notes (tracked, NOT executed)
# impact.severity: "low" | "medium" | "high" | "critical"

The impact engine:

1. Matches the tool against registered impact rules using glob patterns
2. Identifies affected entities (downstream systems, data stores, APIs)
3. Walks steward-confirmed ks_subject_link rows so a record in one system reports its linked records in others (in_scope). Auto-resolved links are advisory and cannot authorize a write. There is no single view of the entity until a steward confirms the match.
4. Computes severity based on the number and type of affected entities
5. Records the compensating-action plan where a rule supplies one (for accountability — Praxom does not execute it)
6. Aggregates plan entries into human-readable summaries

Architects list, confirm, and reject links at GET/POST /api/v1/praxom/subject-links (console: Control → Subject links). Confirm is attested and promotes confidence to 1.0. Reject zeroes confidence and keeps the row so the next resolve cannot silently re-link.

Data StructuresCopy Anchor Link

AffectedEntity describes a single affected entity:

• name — Entity identifier
• type — Entity type (database, api, queue, etc.)
• relationship — How this entity is affected (direct, cascade, etc.)
• reversible — Whether the change is reversible (informational; Praxom records this, it does not perform the reversal)

ImpactSet aggregates the blast radius:

• affected_entities — List of all affected entities
• severity — Aggregate severity level
• compensation_plan — Combined compensating-action notes (recorded for undo accountability; not an executor)
• hash — Deterministic hash for attestation signing

ArchitectureCopy Anchor Link

The target model integrates with the PDP:

Proposed Action
    ↓
ToolActionClassifier
    ├── Read → Pass-through (no evaluation)
    └── Action → PolicyEngine + ImpactEngine
                     ↓
              PolicyDecision + ImpactSet
                     ↓
              AttestationStore (records both)

Impact sets are hashed and included in attestation signatures, ensuring the blast radius computation is part of the tamper-evident audit trail.

ConfigurationCopy Anchor Link

Impact rules are managed via the REST API:

POST /api/v1/praxom/impact-rules
{
  "workspace_id": "ws-1",
  "tool_patterns": ["salesforce.delete_*"],
  "affected_entities": [
    {"name": "Salesforce CRM", "type": "api", "relationship": "direct", "reversible": false},
    {"name": "Data Warehouse", "type": "database", "relationship": "cascade", "reversible": true}
  ],
  "severity": "high"
}

Technical DetailsCopy Anchor Link

• Tool classification caching uses per-workspace TTL to handle dynamic tool registration
• Impact rule matching uses fnmatch glob patterns (_tool_matches_patterns())
• The hash_impact_set() function produces a deterministic hash for attestation signing
• Compensation plans are aggregated from individual entity plans via _aggregate_plans() — the plan is recorded with the attestation; Praxom executes steward-confirmed compensating actions through the shipped connectors (generic HTTP, Slack message delete, Salesforce sandbox record delete); everything else is tracked, not executed
• The impact engine is PostgreSQL-only — no LLM or Oxigraph dependency