Skip to main content

Runtime And Service Flows

Documentation Map​

Runtime And Service Flows

Tool / Contract Summary​

jhf-dobby is a Python service plus worker that converts runtime traces into governed adaptive-learning decisions. It owns learning-state persistence and lifecycle orchestration, but it does not own Fabric governance truth, Warp approval truth, or Shuttle/Bobbin domain truth.

Business Value​

  • centralizes adaptive-learning runtime logic in one bounded service
  • keeps proposal and activation state explicit instead of hidden in ad hoc automation
  • makes failures degrade toward lower-permission modes instead of silent drift

Current Verified State​

Available now:

  • API service process built by src/jhf_dobby/api/app.py (src/jhf_dobby/api/app.py)
  • learning orchestration in src/jhf_dobby/learning/service.py (src/jhf_dobby/learning/service.py)
  • SQLAlchemy persistence in src/jhf_dobby/persistence/ (src/jhf_dobby/persistence)
  • background worker in src/jhf_dobby/worker/service.py (src/jhf_dobby/worker/service.py)
  • live compose runtime with API, worker, and Postgres containers

Planned / not in current scope:

  • distributed job queue
  • autonomous code mutation
  • local policy/admission engine

Available Now​

API service​

The API process exposes health, readiness, version, contract, learning, proposal, and metrics routes. It is stateless except for its use of the persistence layer and external contract readers.

Learning orchestration​

The learning service performs:

  • trace intake and deterministic sampling
  • replay evaluation and threshold checks
  • proposal creation and state transitions
  • Warp approval checks
  • activation and rollback
  • metrics rendering and readiness shaping

Persistence​

Persistence owns these durable records:

  • RunRecord
  • ReplayRecord
  • ProposalRecord
  • MetricCounter

It supports SQLite in local/test paths and Postgres in the live stack.

Worker​

The worker scans proposals that require revalidation and expires them if they still sit in active lifecycle states. It does not run replay jobs, activation jobs, or external sync jobs.

Public Surfaces​

  • docs/API.md
  • fabric-manifest.json (fabric-manifest.json)
  • deploy/compose/jhf-dobby.stack.yml (deploy/compose/jhf-dobby.stack.yml)

Runtime Flow: Intake To Run Record​

Trigger:

  • POST /api/v1/learning/signals/intake

Input:

  • tenant reference
  • trace id
  • correlation id
  • outcome
  • guardrail decision
  • family version set
  • optional steps, source events, target hints

Processing:

  1. reject inconsistent tenant data
  2. reject BLOCK guardrail results
  3. reject security-critical traces
  4. compute deterministic run hash and provenance hash
  5. query Shuttle evidence optionally
  6. sample neutral success traces deterministically
  7. persist a run record unless an identical hash already exists

Outputs / side effects:

  • durable RunRecord
  • updated intake metric
  • optional learning-signal counter increment

Fail-closed behavior:

  • invalid tenant, guardrail, or security inputs return 422
  • Shuttle absence does not block intake

Runtime Flow: Replay Evaluation​

Trigger:

  • POST /api/v1/learning/replay/evaluate

Input:

  • target type and id
  • family versions
  • replay metric bundle
  • replay threshold contract
  • workload similarity flag

Processing:

  1. reject weight_training_candidate
  2. compute candidate and provenance hashes
  3. compare candidate metrics against baseline
  4. apply threshold mode and veto metrics
  5. require workload similarity
  6. force revalidate_required verdict if family versions drift
  7. block if replay budget window is exhausted

Outputs / side effects:

  • durable ReplayRecord
  • replay budget gauges
  • dobby_revalidate_required_total counter when applicable

Fail-closed behavior:

  • budget exhaustion returns 422
  • unsupported target types return 422

Runtime Flow: Proposal, Approval, Activation​

Trigger:

  • POST /api/v1/learning/promotions/propose
  • POST /api/v1/learning/promotions/approve-check
  • POST /api/v1/learning/promotions/activate
  • POST /api/v1/learning/promotions/rollback

Processing:

  1. proposal creation validates mode, risk, replay verdict, no-learn zone, and target constraints
  2. Warp approval check transitions from proposal_generated to replay_validated
  3. Warp approval payload binds candidate and provenance hashes
  4. fail-closed Warp outcomes keep or move proposals into blocked states
  5. medium/high/critical proposals require human approval
  6. Bobbin-marked provenance is published only after successful approval processing
  7. activation checks service mode, proposal state, conflicts, and promotion velocity breaker
  8. rollback restores the stored runtime baseline boundary

Outputs / side effects:

  • durable ProposalRecord state transitions
  • Bobbin JSONL artifact when enabled
  • velocity and denial metrics

Fail-closed behavior:

  • missing/stale/mismatched Warp approvals do not activate anything
  • Fabric drift reduces effective service mode
  • no conflicting activation can proceed

Worker Flow​

Trigger:

  • long-running python -m jhf_dobby.worker.service

Start condition:

  • worker container starts and loops every five seconds

Input:

  • ProposalRecord rows with revalidate_required=true

Processing:

  1. open a DB session
  2. select queued revalidation proposals
  3. expire active ones
  4. update replay queue depth metric when work was processed

Recovery behavior:

  • persistence exceptions return 0 for the cycle
  • the loop continues on the next interval

Readiness / Drift / Monitoring​

  • readiness depends on Fabric alignment plus persistence availability
  • Fabric drift lowers the effective service mode
  • persistence outages degrade readiness and metrics instead of hanging indefinitely
  • crash recovery is handled by compose restart policy in the live stack

Known Limits​

  • no queue broker
  • no long-term scheduler beyond the worker loop
  • no route-level auth implementation inside the FastAPI app
  • no Fabric shadow truth cache
  • jhf-dobby#1
  • jhf-dobby#27
  • jhf-dobby#30
  • jhf-dobby#31
  • jhf-dobby#32
  • jhf-dobby#34
  • jhf-dobby#35
  • jhf-dobby#36

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