Pharos Framework

← Back

Pharos Framework Operations, Jobs, and Benchmark Contracts

Pharos cannot make credible Django, FastAPI, or Rails comparison claims if jobs, deploys, and benchmark claims are informal. They need explicit contracts.

Job Contract

Every job surface must specify:

  • job_id
  • payload_shape
  • enqueue_source
  • retry_policy
  • schedule_mode
  • idempotency_key
  • trace_linkage

Example shape:

{
  "job_id": "notify_invoice_approved",
  "payload_shape": ["invoice_id", "tenant_id", "recipient_user_id"],
  "enqueue_source": "approve_invoice action",
  "retry_policy": "max_retries=5 exponential_backoff",
  "schedule_mode": "immediate",
  "idempotency_key": "invoice_id + recipient_user_id + template_id",
  "trace_linkage": "workflow_transition_trace_id"
}

Deployment Topology Contract

Every supported topology must specify:

  • topology_id
  • app_runtime_shape
  • db_runtime_shape
  • storage_runtime_shape
  • health_probe_surface
  • backup_restore_surface
  • migration_gate_surface

Required topologies:

  • local_single_process
  • local_split_app_and_db
  • managed_db_app_server

Environment Contract

Every deployable app must specify or derive through shared config plus app-local override:

  • environment
  • apps_dir for runtime discovery
  • required_env_vars
  • required_secrets
  • optional_feature_flags
  • config_validation_report
  • config_override_precedence

Pharos should enforce:

  • shared pharos.conf as the framework-wide baseline
  • <app>/app.conf as the app-local override surface
  • secret-bearing values referenced through environment-backed indirection such as db_password_env
  • operator-visible validation through doctor and deploy check

Pharos should reject:

  • undeclared required secrets
  • topology-specific config hidden outside the deployment contract
  • secret material checked into framework or app config when an environment reference is required

Health and Drift Contract

Every deployed app must specify:

  • health_endpoint
  • readiness_endpoint
  • liveness_endpoint
  • migration_status_report
  • drift_status_report
  • restore_verification_report

Benchmark Scenario Contract

Every benchmark scenario must specify:

  • scenario_id
  • app_family
  • competitor_set
  • fixture_dataset
  • workload_shape
  • measured_metrics
  • hardware_runtime_assumptions

Required app families:

  • generated_admin_crud
  • authenticated_workflow
  • list_detail_filter_search
  • background_job_trigger
  • migration_deploy_restore

Required competitor set:

  • django
  • fastapi
  • rails

Scorecard Contract

Every comparative scorecard must specify:

  • scorecard_id
  • scenario_id
  • framework
  • result_timestamp
  • metrics
  • pass_fail_claims

Required metrics:

  • setup_effort
  • median_latency_ms
  • p95_latency_ms
  • crud_throughput
  • cold_start_ms
  • memory_mb
  • migration_time_ms
  • test_suite_time_ms
  • deploy_restore_time_ms
  • observability_replay_completeness

Pharos should reject benchmark claims that lack fixed scenarios, fixed competitor implementations, or fixed metric schema.