Skip to main content

Phase 0 Contracts (North Star Bootstrap)

FleetForge Phase 0 codifies the primitives shared by delivery, policy, replay, and upcoming adapters. Treat this document as the companion to the new embedded schemas and storage defaults—every surface (runtime, SDKs, UI, adapters) should defer to these definitions.

Canonical Schemas​

  • api/schemas/run_spec.json — Run submission contract (DAG + inputs + seed + labels + breakpoints). Reference. The runtime rejects specs that do not validate against this schema or that omit a positive seed.
  • api/schemas/step.json — Step schema (reference) covering all step types.
  • api/schemas/run.json & run_event.json — Serialized run records and event envelopes (reference / run_event). Useful for SDK taps, ClickHouse exporters, and replay tooling.
  • api/schemas/artifact.json — Metadata contract for blobs persisted to the object store (reference).
  • api/schemas/agent_run.json — Adapter envelope for LangGraph/AutoGen/CrewAI integrations (reference). The new AgentRunAdapter trait in core/runtime/src/adapters.rs produces data that must validate against this schema.

👉 Docs and SDK generators should link to these files instead of duplicating schema snippets.

Storage Bootstrap​

  • Postgres migrations live under core/storage/migrations/. Running sqlx migrate run (or just db-migrate) installs the baseline run/step/artifact tables required for Phase 0.
  • Object store layout uses a content-addressable prefix: sha256/<first-byte>/<second-byte>/<full-digest>. See core/storage/src/lib.rs::ObjectStoreArtifactStore::path_for_digest for the canonical mapping.
  • Retention workers and SQLx offline data remain unchanged; just demo primes the schema and object store in local environments.

Telemetry Bootstrap​

  • The OTEL Collector profiles at deploy/otel/collector.local.yaml (local) and deploy/compose/otel-collector-config.yaml (full stack) are the supported Phase 0 entry points.
  • Runtime binaries emit OTLP traces/metrics/logs; export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 (or your collector endpoint) before launching the runtime to capture spans immediately.
  • ClickHouse remains the default sink for run/step telemetry. The collector configs fan OTLP traffic into ClickHouse via the community exporter—ensure the telemetry database exists before bootstrapping.

Adapter Scaffolding​

  • core/runtime/src/adapters.rs introduces AgentRunAdapter, AgentRunContext, and AgentRunEnvelope. Default implementations produce schema-compliant envelopes for start, emit, checkpoint, complete, and error.
  • Framework adapters should construct payloads/checkpoints that serialise to JSON and rely on AgentRunEnvelope::validate() during development to catch schema drift.
  • The runtime re-exports these types so SDKs/adapters can depend on fleetforge-runtime without pulling in unrelated modules.

Acceptance Checklist​

  1. Run submission fails fast if the run spec (or seed) violates the new schema.
  2. The LangGraph Hello Fleet DAG (examples/_packs/demo-pack/agent_team/run_spec.json) runs locally, persisting run/step rows and emitting OTEL spans via the collector configs above.
  3. Artifact uploads land under the content-addressed prefix (inspect via just demo + the toolbox worker).
  4. Adapter scaffolding validates envelopes against agent_run.json, ensuring the planned LangGraph/AutoGen/CrewAI integrations speak the same protocol.