Clone Service Module

Overview

The clone module owns clone identity, strategy persistence, entitlement projection, and public profile/moderation state. It is the source of truth for who owns a clone and which strategy/entitlement runtime modules should use.

It does not execute trades, verify payments, price auditions, or decide lifecycle outcomes.

Responsibilities

• Store, list, read, and update user-owned clone records.
• Persist one editable strategy draft per clone.
• Publish immutable strategy versions and keep one active version.
• Project effective clone entitlements from Economy or debug/manual grants.
• Enforce model-strength and capacity constraints at clone update/strategy paths.
• Store public clone profiles, reports, moderation actions, retirement, and reinstatement.
• Provide clone ownership checks used by API routes and downstream modules.

Boundary Rules

• Clone Service owns effective entitlement rows; Economy owns the payment/purchase facts that create grants.
• Paid product clone creation starts in Economy after deposit verification; Clone Service does not expose a direct create route.
• AI Trading reads strategy drafts/versions and entitlements, but Clone Service owns persistence.
• Lifecycle reads clone identity/owner/public-profile state before auditions and Arena admission.
• Public profile moderation lives here, not in Lifecycle.
• Public names live in clone_public_profiles; clones.display_name is the owner/private operational name.
• Product-facing clone lifecycle state is derived from Clone Service plus Lifecycle facts. Do not expose raw clones.status as the user's clone progress label.

Runtime Flow

Clone strategy flow:

Economy verifies paid creation deposit
-> create clone
-> initialize default draft graph
-> owner edits draft
-> save/publish compiles and validates graph
-> publish transaction deactivates old active version
-> insert immutable active version
-> runtime modules read active/draft strategy as needed

Entitlement flow:

Economy verifies purchase
-> Economy calls entitlement repository
-> clone_capacity_entitlements row is upserted
-> Clone Service projects effective entitlement
-> AI/Prop/Backtesting enforce tier and model strength

Public profile flow:

Owner submits profile
-> v1 auto-approves unless retired
-> public read exposes approved profiles
-> users report profiles
-> admin resolves report, retires, or reinstates profile

Lifecycle display state:

Clone Service setup/profile/version facts
+ Lifecycle audition, Promotion Queue, and Arena membership facts
-> setup_required | configured | audition_running | audition_failed
   | competition_eligible | competing | retired

Main Code Paths

Path	Purpose
backend/src/modules/clone/repositories/clones.ts	Clone records, owner lookup, active clone listing.
backend/src/modules/clone/repositories/clone-strategies.ts	Draft graph persistence and immutable published versions.
backend/src/modules/clone/repositories/entitlements.ts	Effective entitlement projection and upsert.
backend/src/modules/clone/entitlement-policy.ts	Model-strength entitlement checks.
backend/src/modules/clone/public-profile-service.ts	Public profile submit/read/report/moderation workflows.
backend/src/modules/clone/repositories/public-profiles.ts	Public profile persistence.
backend/src/modules/clone/repositories/clone-reports.ts	User report persistence.
backend/src/modules/clone/repositories/moderation-actions.ts	Admin moderation audit persistence.
backend/src/api/server.ts	Clone strategy draft, dry-run, backtest, publish, versions, and entitlement route dispatch.
backend/src/api/routes/public-profile.ts	Public profile and moderation route family.

State And Tables

Migration	Tables
0001_initial.sql	clones, clone_strategy_drafts, clone_strategy_versions, clone_capacity_entitlements, clone_trade_universe, clone_asset_selection_rules
0004_add_clone_entitlement_sync_fields.sql	Economy/entitlement sync fields on clone_capacity_entitlements.
0013_clone_public_profiles_moderation.sql	clone_public_profiles, clone_moderation_actions
0015_clone_reports.sql	clone_reports
0016_clone_public_profile_username.sql	Public username and active username uniqueness.

Table	Technical significance
clones	Canonical clone id, owner user id, operational display name, model, internal runtime/admin status.
clone_strategy_drafts	One editable graph per clone; default graph returned when no row exists.
clone_strategy_versions	Immutable published graph snapshots; publish transaction keeps one active version.
clone_capacity_entitlements	Effective tier, max active assets, allowed model strength, source, sync ids, expiry/revocation.
clone_public_profiles	Public display name, username, bio, avatar, status, submit metadata.
clone_reports	User reports against public profiles; owners cannot self-report.
clone_moderation_actions	Admin and owner-publication audit history.

Routes And Workers

Route family	Purpose
GET /api/v1/clone/clones	List authenticated user's clones.
GET/PATCH /api/v1/clone/clones/:id	Read/update clone.
/api/v1/clone/clones/:id/strategy/draft	Read/update strategy draft.
POST /api/v1/clone/clones/:id/strategy/publish	Publish immutable active version.
GET /api/v1/clone/clones/:id/strategy/versions	List published versions.
GET /api/v1/clone/clones/:id/entitlement	Read effective entitlement. Entitlement writes are internal repository calls from Economy/operator code.
/api/v1/clone/clones/:id/public-profile	Owner public profile submit/read.
GET /api/v1/public/clones/:id/profile	Public profile read.
POST /api/v1/public/clones/:id/report	Report public profile.
/api/v1/admin/moderation/*	Admin report review, retire, reinstate, history.

Clone Service has no worker. Runtime workers consume clone records and strategies from other modules.

Failure Behavior

• Unknown model ids are treated as highest model strength for entitlement enforcement.
• Default local/mock entitlement is Starter when no active entitlement row exists.
• Strategy publish runs in a transaction so prior active versions are deactivated with the new version insert.
• Owner profile submit auto-approves in v1, but retired profiles block owner resubmit until admin reinstates.
• Usernames must be 3-32 lowercase letters, numbers, or underscores and unique among non-retired profiles.
• Profile avatar URLs must be http or https.
• Owners cannot report their own clone profile.

Debugging Notes

• If runtime says a clone has no strategy, check both draft fallback behavior and active clone_strategy_versions.
• If model updates fail, check clone_capacity_entitlements.allowed_model_strength.
• If a profile does not appear publicly, check clone_public_profiles.status and moderation history.
• If Arena admission skips a clone, confirm the public profile is approved.
• If Economy granted an entitlement but runtime does not see it, check entitlement status/effective/expiry fields and sync ids.
• If the UI displays the wrong lifecycle label, check active strategy version, latest audition status, Promotion Queue entry, and Arena membership before checking clones.status.

Tests

cd backend
npm run typecheck
node --import tsx --test test/clone-strategy-repository.test.ts test/clone-public-profile-service.test.ts test/api-pipeline.test.ts

Known Gaps

• Frontend integration for SIWE-backed clone create/list and public profile screens.
• Broader race lifecycle and Arena views consume Clone Service state but are owned outside this module.