Clone Service

Status: draft for alignment

Related:

• High-Level System Design
• Domain Language
• Product Controls
• Prop Trading Module

Purpose

Clone Service owns the canonical clone product record and the private strategy configuration users edit in the builder.

It answers:

Who owns this clone?
What is its public identity?
What strategy has the creator configured?
Which immutable strategy version should runtime systems use?

It does not execute trades, mutate prop account balances, collect payments, run models, settle races, or own market data.

Boundary Summary

Clone Service
  -> clone identity
  -> public clone profile
  -> private strategy draft
  -> immutable strategy versions
  -> internal clone-row status

AI Trading Engine
  -> reads strategy versions
  -> assembles context and prompts
  -> creates decision runs and action proposals

PropTradingEngine
  -> owns prop account existence and account attribution
  -> validates actions and mutates account truth

ContestLifecycleService
  -> owns auditions, races, entries, promotion, retirement, and settlement
  -> stores run-specific pointers such as race entry -> propAccountId

Core Nouns

Clone

A clone is the product actor and strategy owner. It includes the backend clone ID, owner user ID, selected model or model tier, and lifecycle facts derived from setup, audition, queue, Arena, and retirement state.

The clone is not a trading account. One clone can have many prop accounts over time.

Product-facing progress is derived as a lifecycle state instead of read directly from clones.status:

State	Meaning
setup_required	Clone shell exists, but setup is incomplete.
configured	Clone is configured enough to submit for audition.
audition_running	Latest audition is running or being evaluated.
audition_failed	Latest audition failed or was voided; retry is available.
competition_eligible	Audition passed and the clone is eligible for Arena placement.
competing	Clone currently holds an Arena slot.
retired	Clone is out of active competition and preserved as career history.

Public Profile

Backer-facing identity and display metadata: name, description, image/avatar, visible capability signals, and moderation status.

The public profile should not expose the private trading prompt or detailed strategy graph. Public asset/source information should only reflect fields the creator explicitly configures or chooses for public display, not inferred private strategy details.

Strategy Draft

The mutable private strategy configuration the creator edits.

The persisted graph shape remains:

Data Stream Block -> Asset Block -> Trading Prompt Block

The visual Trading Clone Block remains layout/builder metadata, not an executable strategy node.

Strategy Version

An immutable snapshot of a strategy draft that runtime systems can reference.

Auditions and races should use a strategy version, not the latest editable draft. This keeps decision runs, prop account results, and lifecycle outcomes reproducible.

Entitlement

Capacity and model-strength rights for one clone.

Clone Service can enforce active entitlement state when saving or publishing strategy configuration, but EconomyService owns the purchase/payment facts that grant or revoke entitlement.

The practical boundary is:

EconomyService
  -> payment, purchase, and grant facts

Clone Service
  -> effective clone entitlement projection
  -> entitlement reads
  -> save/publish/model-update enforcement

AI Trading Engine
  -> consumes effective entitlement as a runtime guard
  -> does not grant or mutate entitlement

Boundary Rules

Clone Service owns clone identity, public profile, private strategy drafts, immutable strategy versions, and internal clone-row status.

It does not own auth/session truth, payments, market data, model execution, prop account state, or contest lifecycle state.

Versioning Rules

Drafts are mutable and can be saved frequently by the creator.

Publishing freezes the current draft into a strategy version. Publication should validate graph shape, entitlement limits, and ownership. It should not create a prop account by itself.

For this release, each clone has one active published strategy version. Audition and race flows should use that active version rather than choosing arbitrary historical versions.

Sandbox runs are out of scope for the current product flow. If sandbox execution returns later, it should still run against an explicit draft snapshot or strategy version rather than mutable draft state.

Runtime systems should receive explicit identifiers:

cloneId
strategyVersionId
propAccountId, when a prop-backed run exists

Automatic runners should schedule from active lifecycle entries or active prop-backed runs, not from clones alone.

Runtime Handoffs

Create And Configure

UserService authenticates user
-> Clone Service creates clone shell
-> Clone Service saves public profile draft
-> Clone Service saves private strategy draft
-> Clone Service publishes strategy version

Start Audition Or Race

ContestLifecycleService checks product eligibility
-> Clone Service returns clone facts and active strategyVersionId
-> PropTradingEngine creates one prop account with cloneId + strategyVersionId
-> ContestLifecycleService stores the run-specific propAccountId pointer

Run Automatically

Runner lists active lifecycle entries or active prop-backed runs
-> each runnable unit already has cloneId + strategyVersionId + propAccountId
-> AITradingEngine proposes actions
-> PropTradingEngine validates and mutates account truth

Implementation Notes

Current backend storage covers the first vertical slice of this boundary: minimal clone records, clone_strategy_drafts, clone_strategy_versions, and capacity entitlement rows. Clone entitlement policy code lives under the Clone Service module even while the physical service is still the combined backend.

The client-facing route/type contract lives in doc/openapi/client-api.openapi.yaml and generated types in shared/src/generated/client-api.d.ts. Strategy graph implementation details still reuse the workflow builder's existing data stream, asset selection, and trading prompt graph shape.

Open Decisions

• Public profile moderation gating is deferred. We still need to decide whether it blocks draft publication, audition start, or both.
• A combined lifecycle summary read model is still needed so clients can render lifecycle state without joining Clone Service, Audition, Promotion Queue, and Arena reads themselves.