Best-of groups

A best-of group ties several execution tasks together under one group_id so they can be created and evaluated as a set. The only behavior the code actually implements is a cross-ring admission check on task creation. There is no per-strategy logic and no winner promotion — read the caveats below before you build on it.

The shape

Tasks carry an optional best_of_group describing their membership (src/db/adapter.ts:268-276):

interface BestOfGroup {
  group_id: string;
  index: number;
  total: number;
  kind?: "best_of" | "variants" | "shadow" | "race";
  label?: string;
  acceptance_hash: string;
  group_spec_ref?: { kind: ResourceKind | string; id: string };
}

Cross-ring admission

evaluateBestOfCreatePolicy runs on every tasks.create (src/best-of/policy.ts:94). A task with no group_id fast-returns { allowed: true }. For a group, it lists all members, collects their rings, and decides:

Condition	Result
All members share one ring	Allowed — single-ring groups skip the rest
Members span >1 ring, no group_spec_ref	BEST_OF_GROUP_SPEC_REQUIRED
Caller lacks access to any member ring	BEST_OF_GROUP_RING_ACCESS_DENIED
group_spec_ref not visible to caller	BEST_OF_GROUP_SPEC_NOT_VISIBLE
Otherwise	Allowed

The spec-ref visibility check resolves signal, workspace_item, workspace_revision, and artifact refs against the caller’s ring scope (policy.ts:40-72). Every decision — accept or reject — writes an audit event (auditDecision, policy.ts:74-92).

Note

Ring access is the unit of admission. A cross-ring group only succeeds when the caller can see every member ring and the shared group_spec_ref. This is the entire policy — there is nothing scoring or comparing the tasks themselves.

What is not implemented

The kind field is decorative

kind?: "best_of" | "variants" | "shadow" | "race" exists on the type but no handler, policy, or diagnostic branches on it — only group_id and the cross-ring policy matter (gap-3 F11). The four strategy names are aspirational schema. Do not assume “variants”, “shadow”, or “race” produce differentiated behavior; they do not.

There is no winner promotion or reconciliation

best_of_groups.reconcile (src/commands/handlers/tasks.ts:573-603) sounds like it selects or finalizes a winner. It does not. It lists the group’s visible members, computes a redacted-member count, writes a best_of_group_reconcile_public audit event, and returns the visible set. It mutates no group or task state (gap-3 §1.6). The HTTP surface is GET /best-of-groups/:id/reconcile — a read-shaped verb that still writes an audit row. Nothing in Chorus picks a winner across a best-of group; that is left to the caller.

Group reads are storage-filtered and bounded

Admission and public reconciliation push group_id into the storage query and hydrate at most 100 members. A one-row storage lookahead rejects a legacy/corrupt group with more than 100 members instead of silently truncating its policy view. The public create schema also caps best_of_group.total at 100. This keeps both the create hot path and reconcile response independent of the total task-table size; callers that need larger experimental cohorts should split them across group IDs.