Skip to main content

Data Model

Documentation Map​

Data Model

Scope​

This document summarizes the main persistent and integration-relevant entities in jhf-warp. It is not a full ORM reference.

Main Objects​

TaskProfile / Classification Result​

  • purpose: classify incoming work and derive risk/domain/setup hints
  • important identifiers: request-local task/category/domain keys

TeamSetup / BootstrapBundle​

  • purpose: represent desired agent composition and bootstrap instructions
  • important identifiers: domain IDs, agent slugs, role/profile keys

TopologySnapshot / TopologyDiff / PatchPlan​

  • purpose: represent current runtime state, desired state, and guarded mutation plan
  • important identifiers: graph revision, agent slugs, channel edges, runtime compatibility labels

AuditEvent / RolloutRecord​

  • purpose: durable operator/audit history
  • important identifiers: event IDs, rollout IDs, timestamps, event type

AgentLease​

  • purpose: coordinate bounded control-agent dispatch ownership
  • important identifiers: lease_id, target_agent_id, expires_at

SchedulerRun​

  • purpose: idempotent control-agent cycle tracking
  • important identifiers: cycle_id, run ID, started/finished timestamps

WatchdogObservation​

  • purpose: durable non-destructive control-plane observations
  • important identifiers: observation ID, agent ID, severity, evidence

PersistentDomainAgentProfile​

  • purpose: durable identity/governance metadata for persistent domain agents
  • important identifiers: agent_slug, display name, domain ID, tool profile ID
  • create/adopt guardrail: future runtime creation of a new persistent-agent record must require the Spindle-backed business-link contract in docs/SPINDLE_AGENT_REGISTRATION_REQUEST_CONTRACT.md

WorkspaceRecord​

  • purpose: track persistent workspace ownership, lifecycle, and retention policy
  • important identifiers: workspace ID/path, owning agent slug, policy/lifecycle state

LearningProposal​

  • purpose: proposed, reviewed, and approved/rejected learning changes for persistent agents
  • important identifiers: proposal ID, target agent slug, review status

ToolProfile​

  • purpose: formalize allowed tool/capability envelopes for persistent agents
  • important identifiers: tool_profile_id, capability keys, allowed operations
  • additional contract fields: system_overlays for explicit read-first ERPNext/Frappe or similar business-system access envelopes

Relationships​

  • a persistent domain agent can own one persistent workspace record
  • a persistent domain agent can have many learning proposals
  • a persistent domain agent references one tool profile
  • a scheduler run can produce many dispatch decisions and watchdog observations
  • a target agent can have many leases over time but only bounded active ownership at once

Persistence Assumptions​

  • durable state uses Postgres
  • schema ownership is handled through Alembic migrations
  • fixture-memory is a non-durable development/test fallback

Integration Relevance​

Fabric-, wiki-, and update-oriented consumers care most about:

  • agent slugs and stable IDs
  • lifecycle state
  • topology/runtime compatibility signals
  • workspace retention state
  • learning proposal governance state
  • migration-sensitive persistence ownership

License​

AGPLv3. See ../LICENSE (LICENSE). Learn more at helpifyr.com.