@xfxstudio/claworld 0.1.0

package/src/product-shell/contracts/world-orchestration.js

@@ -0,0 +1,1024 @@
+function normalizeText(value, fallback = null) {
+  if (value == null) return fallback;
+  const normalized = String(value).trim();
+  return normalized || fallback;
+}
+
+function normalizeInteger(value, fallback = 0) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.max(0, Math.trunc(parsed));
+}
+
+function normalizeNumber(value, fallback = null) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return fallback;
+  return parsed;
+}
+
+function normalizeStringList(values = []) {
+  if (!Array.isArray(values)) return [];
+  return [...new Set(values.map((value) => normalizeText(value, null)).filter(Boolean))];
+}
+
+function normalizeBroadcastConfig(broadcast = {}) {
+  return {
+    enabled: broadcast.enabled === true,
+    audience: normalizeText(broadcast.audience, 'members'),
+    replyPolicy: normalizeText(broadcast.replyPolicy, 'zero'),
+    excludeSelf: broadcast.excludeSelf !== false,
+  };
+}
+
+function isEmptyProfileValue(value) {
+  if (value == null) return true;
+  if (typeof value === 'string') return value.trim() === '';
+  if (Array.isArray(value)) return value.length === 0 || value.every((entry) => isEmptyProfileValue(entry));
+  if (typeof value === 'object') {
+    const entries = Object.values(value);
+    return entries.length === 0 || entries.every((entry) => isEmptyProfileValue(entry));
+  }
+  return false;
+}
+
+function normalizeProfileValue(value) {
+  if (typeof value === 'string') return value.trim();
+  if (Array.isArray(value)) {
+    return value
+      .map((entry) => normalizeProfileValue(entry))
+      .filter((entry) => entry !== undefined && !isEmptyProfileValue(entry));
+  }
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value)
+        .filter(([, entry]) => entry !== undefined)
+        .map(([key, entry]) => [key, normalizeProfileValue(entry)]),
+    );
+  }
+  return value;
+}
+
+export function normalizeProfile(profile = {}) {
+  if (!profile || typeof profile !== 'object' || Array.isArray(profile)) return {};
+
+  return Object.fromEntries(
+    Object.entries(profile)
+      .filter(([key, value]) => normalizeText(key, null) && value !== undefined)
+      .map(([key, value]) => [normalizeText(key, null), normalizeProfileValue(value)]),
+  );
+}
+
+export function mergeProfileState(profile = {}, profileUpdate = {}) {
+  return {
+    ...normalizeProfile(profile),
+    ...normalizeProfile(profileUpdate),
+  };
+}
+
+function normalizeLookupText(value) {
+  return normalizeText(value, '')?.toLowerCase() || '';
+}
+
+function sentenceCase(value, fallback = '') {
+  const normalized = normalizeText(value, fallback);
+  if (!normalized) return fallback;
+  return /[.!?]$/.test(normalized) ? normalized : `${normalized}.`;
+}
+
+function quoteExample(example) {
+  return `"${String(example).trim()}"`;
+}
+
+function joinAsNaturalLanguage(values = []) {
+  const items = values.filter(Boolean);
+  if (items.length === 0) return '';
+  if (items.length === 1) return items[0];
+  if (items.length === 2) return `${items[0]} and ${items[1]}`;
+  return `${items.slice(0, -1).join(', ')}, and ${items.at(-1)}`;
+}
+
+function summarizeWorldChoices(items = []) {
+  return items.map((world) => `${world.displayName} [${world.worldId}]`);
+}
+
+function normalizeWorldSummary(world = {}) {
+  const summary = world.agentSummary && typeof world.agentSummary === 'object' ? world.agentSummary : world;
+  const rawWorldId = world.worldId || summary.worldId;
+
+  return {
+    worldId: normalizeText(rawWorldId, 'unknown-world'),
+    displayName: normalizeText(summary.displayName || world.displayName, normalizeText(rawWorldId, 'Unknown World')),
+    summary: normalizeText(summary.summary || world.summary, ''),
+    category: normalizeText(summary.category || world.category, 'general'),
+    hotness: normalizeInteger(summary.hotness || world.hotness || world.activatedMemberCount, 0),
+    requiredFieldCount: normalizeInteger(summary.requiredFieldCount || world.requiredFieldCount, 0),
+    matchingMode: normalizeText(summary.matchingMode || world.matchingMode, 'manual_review'),
+    sessionMode: normalizeText(summary.sessionMode || world.sessionMode, 'a2a'),
+  };
+}
+
+function normalizeField(field = {}, index = 0, { required = false } = {}) {
+  const fieldId = normalizeText(field.fieldId || field.id, `field_${index + 1}`);
+  return {
+    fieldId,
+    label: normalizeText(field.label, fieldId),
+    type: normalizeText(field.type, 'string'),
+    source: normalizeText(field.source, 'profile'),
+    required: field.required === true || required,
+    description: normalizeText(field.description, null),
+    examples: normalizeStringList(field.examples),
+    constraints: field.constraints && typeof field.constraints === 'object' ? field.constraints : {},
+  };
+}
+
+function normalizeSearchSchema(payload = {}, { worldId = null, fallbackFields = [] } = {}) {
+  const rawInputFields = Array.isArray(payload.inputFields) && payload.inputFields.length > 0
+    ? payload.inputFields
+    : fallbackFields;
+  const inputFields = rawInputFields.map((field, index) => normalizeField(field, index, { required: false }));
+  const inputFieldIds = normalizeStringList(
+    Array.isArray(payload.inputFieldIds)
+      ? payload.inputFieldIds
+      : inputFields.map((field) => field.fieldId),
+  );
+
+  return {
+    modelId: normalizeText(payload.modelId, worldId ? `${worldId}.search.v1` : 'world.search.v1'),
+    worldId: normalizeText(payload.worldId, worldId || 'unknown-world'),
+    mode: normalizeText(payload.mode, 'membership_profile_search'),
+    previewRoute: normalizeText(payload.previewRoute, worldId ? `/v1/worlds/${worldId}/search` : '/v1/worlds/:worldId/search'),
+    inputFieldIds,
+    inputFields,
+    resultFields: normalizeStringList(payload.resultFields),
+    viewerRequirement: normalizeText(payload.viewerRequirement, 'active_membership'),
+    onlineOnly: payload.onlineOnly !== false,
+    defaultLimit: normalizeInteger(payload.defaultLimit, 10),
+    summary: normalizeText(payload.summary, ''),
+    hints: normalizeStringList(payload.hints),
+    status: normalizeText(payload.status, 'phase1_world_search'),
+  };
+}
+
+function normalizeWorldDetail(payload = {}) {
+  if (Array.isArray(payload.requiredFields) || Array.isArray(payload.optionalFields)) {
+    const requiredFields = Array.isArray(payload.requiredFields)
+      ? payload.requiredFields.map((field, index) => normalizeField(field, index, { required: true }))
+      : [];
+    const optionalFields = Array.isArray(payload.optionalFields)
+      ? payload.optionalFields.map((field, index) => normalizeField(field, index, { required: false }))
+      : [];
+    const normalizedWorldId = normalizeText(payload.worldId, 'unknown-world');
+
+    return {
+      status: normalizeText(payload.status, 'ready'),
+      source: normalizeText(payload.source, 'product_shell'),
+      worldId: normalizedWorldId,
+      displayName: normalizeText(payload.displayName, normalizedWorldId),
+      summary: normalizeText(payload.summary, ''),
+      description: normalizeText(payload.description, normalizeText(payload.summary, '')),
+      category: normalizeText(payload.category, 'general'),
+      requiredFieldCount: normalizeInteger(payload.requiredFieldCount, requiredFields.length) || requiredFields.length,
+      optionalFieldCount: normalizeInteger(payload.optionalFieldCount, optionalFields.length) || optionalFields.length,
+      matchingMode: normalizeText(payload.matchingMode, 'manual_review'),
+      sessionMode: normalizeText(payload.sessionMode, 'a2a'),
+      interactionRules: normalizeText(payload.interactionRules, null),
+      prohibitedRules: normalizeText(payload.prohibitedRules, null),
+      ratingRules: normalizeText(payload.ratingRules, null),
+      adminAgentIds: normalizeStringList(payload.adminAgentIds),
+      eligibility: normalizeText(payload.eligibility, 'active'),
+      broadcast: normalizeBroadcastConfig(payload.broadcast),
+      requiredFields,
+      optionalFields,
+      hints: normalizeStringList(payload.hints),
+      nextAction: normalizeText(payload.nextAction, 'collect_profile_fields_then_call_join'),
+      sessionOverview: payload.sessionOverview && typeof payload.sessionOverview === 'object' ? payload.sessionOverview : {},
+      matchingOverview: payload.matchingOverview && typeof payload.matchingOverview === 'object' ? payload.matchingOverview : {},
+      searchSchema: normalizeSearchSchema(payload.searchSchema || {}, {
+        worldId: normalizedWorldId,
+        fallbackFields: requiredFields,
+      }),
+    };
+  }
+
+  const world = payload.world && typeof payload.world === 'object' ? payload.world : {};
+  const agentSummary = payload.agentSummary && typeof payload.agentSummary === 'object' ? payload.agentSummary : {};
+  const joinSchema = payload.joinSchema && typeof payload.joinSchema === 'object' ? payload.joinSchema : {};
+  const fieldGuide = payload.fieldGuide && typeof payload.fieldGuide === 'object' ? payload.fieldGuide : {};
+  const sessionOverview = payload.sessionOverview && typeof payload.sessionOverview === 'object'
+    ? payload.sessionOverview
+    : {};
+  const matchingOverview = payload.matchingOverview && typeof payload.matchingOverview === 'object'
+    ? payload.matchingOverview
+    : {};
+  const searchOverview = payload.searchSchema && typeof payload.searchSchema === 'object'
+    ? payload.searchSchema
+    : {};
+
+  const requiredInput = Array.isArray(fieldGuide.required) && fieldGuide.required.length > 0
+    ? fieldGuide.required
+    : (Array.isArray(joinSchema.requiredFields) ? joinSchema.requiredFields : []);
+  const optionalInput = Array.isArray(fieldGuide.optional) && fieldGuide.optional.length > 0
+    ? fieldGuide.optional
+    : (Array.isArray(joinSchema.optionalFields) ? joinSchema.optionalFields : []);
+
+  const requiredFields = requiredInput.map((field, index) => normalizeField(field, index, { required: true }));
+  const optionalFields = optionalInput.map((field, index) => normalizeField(field, index, { required: false }));
+  const worldId = normalizeText(payload.worldId || world.worldId || joinSchema.worldId, 'unknown-world');
+  const displayName = normalizeText(payload.displayName || agentSummary.displayName || world.displayName, worldId);
+
+  return {
+    status: 'ready',
+    source: 'product_shell',
+    worldId,
+    displayName,
+    summary: normalizeText(payload.summary || agentSummary.summary || world.summary, ''),
+    description: normalizeText(payload.description || world.description, normalizeText(payload.summary || agentSummary.summary || world.summary, '')),
+    category: normalizeText(payload.category || agentSummary.category || world.category, 'general'),
+    requiredFieldCount: normalizeInteger(joinSchema.requiredFieldCount, requiredFields.length) || requiredFields.length,
+    optionalFieldCount: normalizeInteger(joinSchema.optionalFieldCount, optionalFields.length) || optionalFields.length,
+    matchingMode: normalizeText(payload.matchingMode || agentSummary.matchingMode || matchingOverview.mode || world.matching?.mode, 'manual_review'),
+    sessionMode: normalizeText(payload.sessionMode || agentSummary.sessionMode || sessionOverview.mode || world.sessionTemplate?.mode, 'a2a'),
+    interactionRules: normalizeText(payload.interactionRules || world.interactionRules, null),
+    prohibitedRules: normalizeText(payload.prohibitedRules || world.prohibitedRules, null),
+    ratingRules: normalizeText(payload.ratingRules || world.ratingRules, null),
+    adminAgentIds: normalizeStringList(payload.adminAgentIds || world.adminAgentIds),
+    eligibility: normalizeText(payload.eligibility || world.eligibility, 'active'),
+    broadcast: normalizeBroadcastConfig(payload.broadcast || world.broadcast),
+    requiredFields,
+    optionalFields,
+    hints: normalizeStringList(payload.hints || joinSchema.hints),
+    nextAction: normalizeText(payload.nextAction || joinSchema.nextAction, 'collect_profile_fields_then_call_join'),
+    sessionOverview,
+    matchingOverview,
+    searchSchema: normalizeSearchSchema(searchOverview, {
+      worldId,
+      fallbackFields: [...requiredFields, ...optionalFields],
+    }),
+  };
+}
+
+function normalizeJoinCheckField(field = {}, index = 0) {
+  return normalizeField(field, index, { required: true });
+}
+
+function normalizeJoinCheckResponse(payload = {}, { worldId = null, profile = {} } = {}) {
+  const missingFields = Array.isArray(payload.missingFields)
+    ? payload.missingFields.map((field, index) => normalizeJoinCheckField(field, index))
+    : [];
+  const guidance = payload.missingFieldGuidance && typeof payload.missingFieldGuidance === 'object'
+    ? payload.missingFieldGuidance
+    : {};
+  const orderedMissingFields = Array.isArray(guidance.orderedMissingFields)
+    ? guidance.orderedMissingFields.map((field, index) => normalizeJoinCheckField(field, index))
+    : missingFields;
+  const fallbackNextMissingField = orderedMissingFields[0] || missingFields[0] || null;
+  const nextMissingField = payload.nextMissingField
+    ? normalizeJoinCheckField(payload.nextMissingField)
+    : (guidance.nextMissingField ? normalizeJoinCheckField(guidance.nextMissingField) : fallbackNextMissingField);
+  const accepted = payload.accepted === true || orderedMissingFields.length === 0;
+
+  return {
+    worldId: normalizeText(payload.worldId, worldId || 'unknown-world'),
+    accepted,
+    status: normalizeText(payload.status, accepted ? 'eligible' : 'needs_profile'),
+    missingFields,
+    nextMissingField,
+    missingFieldGuidance: {
+      mode: normalizeText(guidance.mode, nextMissingField ? 'ordered_required_fields' : 'complete'),
+      orderedMissingFields,
+      orderedMissingFieldIds: normalizeStringList(
+        Array.isArray(guidance.orderedMissingFieldIds)
+          ? guidance.orderedMissingFieldIds
+          : orderedMissingFields.map((field) => field.fieldId),
+      ),
+      nextMissingField,
+      remainingRequiredFieldCount: normalizeInteger(guidance.remainingRequiredFieldCount, orderedMissingFields.length),
+    },
+    normalizedProfile: normalizeProfile(
+      payload.normalizedProfile && typeof payload.normalizedProfile === 'object'
+        ? payload.normalizedProfile
+        : profile,
+    ),
+    nextAction: normalizeText(
+      payload.nextAction,
+      accepted ? 'join_world_when_membership_persistence_exists' : 'collect_missing_profile_fields',
+    ),
+  };
+}
+
+function normalizeProfileSummaryField(field = {}, index = 0) {
+  const fieldId = normalizeText(field.fieldId || field.id, `field_${index + 1}`);
+  const value = Array.isArray(field.value)
+    ? normalizeStringList(field.value)
+    : normalizeText(field.value, null);
+
+  if (value == null || (Array.isArray(value) && value.length === 0)) {
+    return null;
+  }
+
+  return {
+    fieldId,
+    label: normalizeText(field.label, fieldId),
+    value,
+  };
+}
+
+function normalizeCandidateProfileSummary(summary = {}) {
+  return {
+    displayName: normalizeText(summary.displayName, null),
+    headline: normalizeText(summary.headline, null),
+    requiredFields: Array.isArray(summary.requiredFields)
+      ? summary.requiredFields.map((field, index) => normalizeProfileSummaryField(field, index)).filter(Boolean)
+      : [],
+    optionalFields: Array.isArray(summary.optionalFields)
+      ? summary.optionalFields.map((field, index) => normalizeProfileSummaryField(field, index)).filter(Boolean)
+      : [],
+  };
+}
+
+function normalizeCompatibilitySignal(signal = {}, index = 0) {
+  return {
+    signalId: normalizeText(signal.signalId, `signal_${index + 1}`),
+    type: normalizeText(signal.type, 'world_ready'),
+    fieldIds: normalizeStringList(signal.fieldIds),
+    score: normalizeNumber(signal.score, 0),
+    summary: normalizeText(signal.summary, ''),
+  };
+}
+
+function normalizeDeliveryReason(reason = {}) {
+  return {
+    code: normalizeText(reason.code, null),
+    matchedFieldIds: normalizeStringList(reason.matchedFieldIds),
+    summary: normalizeText(reason.summary, ''),
+  };
+}
+
+function normalizeCandidateScoreBreakdown(entries = []) {
+  if (!Array.isArray(entries)) return [];
+
+  return entries.map((entry, index) => ({
+    signalId: normalizeText(entry.signalId, `score_signal_${index + 1}`),
+    label: normalizeText(entry.label, `Signal ${index + 1}`),
+    weight: normalizeNumber(entry.weight, 0),
+    sourceFieldIds: normalizeStringList(entry.sourceFieldIds),
+    matched: entry.matched === true,
+    requesterValue: entry.requesterValue ?? null,
+    candidateValue: entry.candidateValue ?? null,
+    sharedValues: Array.isArray(entry.sharedValues) ? normalizeStringList(entry.sharedValues) : [],
+    overlapCount: normalizeInteger(entry.overlapCount, 0),
+    contribution: normalizeNumber(entry.contribution, 0),
+  }));
+}
+
+function normalizeCandidate(candidate = {}, index = 0) {
+  const normalizedRank = normalizeNumber(candidate.rank, null);
+
+  return {
+    candidateId: normalizeText(candidate.candidateId, `candidate_${index + 1}`),
+    worldId: normalizeText(candidate.worldId, 'unknown-world'),
+    sourceMembershipId: normalizeText(candidate.sourceMembershipId, null),
+    profileSummary: normalizeCandidateProfileSummary(candidate.profileSummary),
+    compatibilitySignals: Array.isArray(candidate.compatibilitySignals)
+      ? candidate.compatibilitySignals.map((signal, signalIndex) => normalizeCompatibilitySignal(signal, signalIndex))
+      : [],
+    deliveryReason: normalizeDeliveryReason(candidate.deliveryReason),
+    expiresAt: normalizeText(candidate.expiresAt, null),
+    joinedAt: normalizeText(candidate.joinedAt, null),
+    rank: normalizedRank == null ? null : Math.max(1, Math.trunc(normalizedRank)),
+    score: normalizeNumber(candidate.score, null),
+    scoreBreakdown: normalizeCandidateScoreBreakdown(candidate.scoreBreakdown),
+    scoringInputs: candidate.scoringInputs && typeof candidate.scoringInputs === 'object' ? candidate.scoringInputs : {},
+  };
+}
+
+function normalizeCandidateFeedResponse(payload = {}, { worldId = null, agentId = null } = {}) {
+  const candidates = Array.isArray(payload.candidates)
+    ? payload.candidates.map((candidate, index) => normalizeCandidate(candidate, index))
+    : [];
+
+  return {
+    worldId: normalizeText(payload.worldId, worldId || 'unknown-world'),
+    agentId: normalizeText(payload.agentId, agentId || null),
+    viewerMembershipId: normalizeText(payload.viewerMembershipId, null),
+    generatedAt: normalizeText(payload.generatedAt, null),
+    expiresAt: normalizeText(payload.expiresAt, null),
+    deliveryMode: normalizeText(payload.deliveryMode, 'agent_review_before_live_session'),
+    nextAction: normalizeText(
+      payload.nextAction,
+      candidates.length > 0 ? 'review_candidates_before_requesting_live_session' : 'wait_for_more_candidates',
+    ),
+    candidateSource: normalizeText(payload.candidateSource, 'active_memberships'),
+    candidateModel: payload.candidateModel && typeof payload.candidateModel === 'object' ? payload.candidateModel : {},
+    strategy: payload.strategy && typeof payload.strategy === 'object' ? payload.strategy : {},
+    limit: normalizeInteger(payload.limit, candidates.length),
+    totalCandidates: normalizeInteger(payload.totalCandidates, candidates.length),
+    status: normalizeText(payload.status, candidates.length > 0 ? 'feed_ready' : 'no_candidates_ready'),
+    candidates,
+  };
+}
+
+function summarizeProfileValue(value) {
+  if (Array.isArray(value)) return joinAsNaturalLanguage(value.map((entry) => String(entry).trim()).filter(Boolean));
+  return normalizeText(value, '');
+}
+
+function summarizeProfileFields(fields = []) {
+  return fields
+    .map((field) => {
+      const value = summarizeProfileValue(field.value);
+      if (!value) return null;
+      return `${field.label}: ${value}`;
+    })
+    .filter(Boolean);
+}
+
+function buildCandidateDeliverySummaryLine(candidateSummary = {}, index = 0) {
+  return `${index + 1}. ${candidateSummary.summary}`;
+}
+
+function formatSessionOverview(detail = {}) {
+  const sessionOverview = detail.sessionOverview && typeof detail.sessionOverview === 'object'
+    ? detail.sessionOverview
+    : {};
+  const mode = normalizeText(detail.sessionMode || sessionOverview.mode, null);
+  const maxTurns = normalizeInteger(sessionOverview.maxTurns, null);
+  const turnTimeoutMs = normalizeInteger(sessionOverview.turnTimeoutMs, null);
+  const parts = [];
+
+  if (mode) parts.push(`${mode} mode`);
+  if (maxTurns != null) parts.push(`max ${maxTurns} turns`);
+  if (turnTimeoutMs != null) parts.push(`${turnTimeoutMs}ms turn timeout`);
+
+  return parts.length > 0 ? parts.join(', ') : null;
+}
+
+function buildRaiseHandDirective(sessionOverview = {}) {
+  const mode = normalizeText(sessionOverview.raiseHandPolicy?.mode, null);
+  if (mode === 'dual_raise_hand') {
+    return 'When you are ready to conclude, include [[CLAWORLD_RAISE_HAND]] in your reply. The round closes once both agents raise hand.';
+  }
+  if (mode === 'single_raise_hand' || mode === 'either_raise_hand') {
+    return 'When you are ready to conclude, include [[CLAWORLD_RAISE_HAND]] in your reply to close the round.';
+  }
+  return null;
+}
+
+export function buildWorldSessionStartupText(detail = {}) {
+  const normalizedDetail = normalizeWorldDetail(detail);
+  const worldId = normalizeText(normalizedDetail.worldId, null);
+  if (!worldId) return null;
+
+  const displayName = normalizeText(normalizedDetail.displayName, worldId);
+  const summary = normalizeText(normalizedDetail.summary, null);
+  const sessionSummary = formatSessionOverview(normalizedDetail);
+  const sessionOverview = normalizedDetail.sessionOverview && typeof normalizedDetail.sessionOverview === 'object'
+    ? normalizedDetail.sessionOverview
+    : {};
+  const raiseHandSummary = normalizeText(sessionOverview.raiseHandPolicy?.summary, null);
+  const openingText = normalizeText(sessionOverview.openingText, null);
+  const convergenceText = normalizeText(sessionOverview.convergence?.text, null);
+  const raiseHandDirective = buildRaiseHandDirective(sessionOverview);
+  const interactionRules = normalizeText(normalizedDetail.interactionRules, null);
+  const prohibitedRules = normalizeText(normalizedDetail.prohibitedRules, null);
+  const ratingRules = normalizeText(normalizedDetail.ratingRules, null);
+
+  const lines = [
+    'Internal Claworld world context for this session.',
+    'Do not acknowledge, paraphrase, or announce this setup to the peer unless it is directly relevant to their message.',
+    `World: ${displayName} [${worldId}]`,
+    summary ? `Summary: ${summary}` : null,
+    sessionSummary ? `Session overview: ${sessionSummary}` : null,
+    raiseHandSummary ? `Completion rule: ${raiseHandSummary}` : null,
+    openingText ? `Opening focus: ${openingText}` : null,
+    interactionRules ? `Interaction rules: ${interactionRules}` : null,
+    prohibitedRules ? `Prohibited rules: ${prohibitedRules}` : null,
+    ratingRules ? `Rating rules: ${ratingRules}` : null,
+    convergenceText ? `Convergence rule: ${convergenceText}` : null,
+    raiseHandDirective ? `Completion signal: ${raiseHandDirective}` : null,
+    'Apply these world rules symmetrically when responding in this session.',
+  ].filter(Boolean);
+
+  return lines.join('\n');
+}
+
+function normalizeSelectionInput(selection) {
+  if (selection && typeof selection === 'object') {
+    const asWorldId = normalizeText(selection.worldId, null);
+    const asDisplayName = normalizeText(selection.displayName, null);
+    const asChoice = normalizeText(selection.selection || selection.choice || selection.value, null);
+    const text = asWorldId || asDisplayName || asChoice || '';
+    return {
+      raw: selection,
+      text,
+      normalized: normalizeLookupText(text),
+      index: /^\d+$/.test(String(text)) ? normalizeInteger(text, 0) : null,
+    };
+  }
+
+  const text = normalizeText(selection, '');
+  return {
+    raw: selection,
+    text,
+    normalized: normalizeLookupText(text),
+    index: /^\d+$/.test(String(text)) ? normalizeInteger(text, 0) : null,
+  };
+}
+
+function buildSelectionRetryContract(status, selection, items = [], matches = []) {
+  const choiceLabel = selection.text ? `"${selection.text}"` : 'that choice';
+  const retryWorlds = (matches.length > 0 ? matches : items).map((world) => normalizeWorldSummary(world));
+  const retrySummary = summarizeWorldChoices(retryWorlds);
+
+  if (status === 'ambiguous') {
+    return {
+      status,
+      selection: {
+        input: selection.text || null,
+        matchedBy: null,
+        worldId: null,
+        displayName: null,
+      },
+      candidateWorlds: retryWorlds,
+      orchestration: {
+        stage: 'post_setup_world_selection_retry',
+        system: 'The world choice matched multiple worlds. Show the narrowed list and ask the user to pick one exact world ID or display name.',
+        user: `The choice ${choiceLabel} is ambiguous. Matching worlds: ${joinAsNaturalLanguage(retrySummary)}. Ask the user to choose one exact world ID or display name.`,
+        followUp: 'Once the user confirms one exact world, fetch its detail and explain the required fields before join-check.',
+      },
+    };
+  }
+
+  return {
+    status: 'no_match',
+    selection: {
+      input: selection.text || null,
+      matchedBy: null,
+      worldId: null,
+      displayName: null,
+    },
+    candidateWorlds: retryWorlds,
+    orchestration: {
+      stage: 'post_setup_world_selection_retry',
+      system: 'The world choice did not match the available world directory. Re-list the worlds and ask the user to choose one by world ID or display name.',
+      user: retrySummary.length > 0
+        ? `I could not match ${choiceLabel} to an available world. Available worlds: ${joinAsNaturalLanguage(retrySummary)}. Ask the user to choose one by world ID or display name.`
+        : 'No worlds are currently available. Tell the user setup is complete but world selection cannot continue yet.',
+      followUp: 'Once the user chooses a valid world, confirm it, fetch the world detail, and explain the required fields before join-check.',
+    },
+  };
+}
+
+export function buildWorldSelectionPrompt(worldDirectory = {}) {
+  const worldLines = Array.isArray(worldDirectory.items)
+    ? worldDirectory.items.map((world, index) => (
+      `${index + 1}. ${world.displayName} [${world.worldId}] - ${world.summary}`
+      + ` (category: ${world.category}; required fields: ${world.requiredFieldCount};`
+      + ` matching: ${world.matchingMode}; session: ${world.sessionMode})`
+    ))
+    : [];
+
+  return {
+    stage: 'post_setup_world_selection',
+    recommendedWorldId: worldDirectory.recommendedWorldId || null,
+    system:
+      'Setup is complete. Present the available worlds, explain the differences briefly, and ask the user to choose one world by worldId or display name. After the choice, confirm the selected world before explaining its required fields.',
+    user:
+      worldLines.length > 0
+        ? `Available worlds:\n${worldLines.join('\n')}\nAsk the user which world they want to join next.`
+        : 'No worlds are currently available. Tell the user setup is complete but no worlds can be selected yet.',
+    followUp:
+      'After the user chooses a world, confirm the selection, fetch that world detail, explain the required fields, and then use join-check for that world.',
+  };
+}
+
+export function resolveWorldSelection(worldDirectory = {}, selection = null) {
+  const items = Array.isArray(worldDirectory.items)
+    ? worldDirectory.items.map((world) => normalizeWorldSummary(world))
+    : [];
+  const normalizedSelection = normalizeSelectionInput(selection);
+
+  if (items.length === 0) {
+    return buildSelectionRetryContract('no_match', normalizedSelection, items);
+  }
+
+  let selectedWorld = null;
+  let matchedBy = null;
+
+  if (normalizedSelection.index && normalizedSelection.index >= 1 && normalizedSelection.index <= items.length) {
+    selectedWorld = items[normalizedSelection.index - 1];
+    matchedBy = 'index';
+  }
+
+  if (!selectedWorld && normalizedSelection.normalized) {
+    selectedWorld = items.find((world) => normalizeLookupText(world.worldId) === normalizedSelection.normalized) || null;
+    if (selectedWorld) matchedBy = 'worldId';
+  }
+
+  if (!selectedWorld && normalizedSelection.normalized) {
+    selectedWorld = items.find((world) => normalizeLookupText(world.displayName) === normalizedSelection.normalized) || null;
+    if (selectedWorld) matchedBy = 'displayName';
+  }
+
+  if (!selectedWorld && normalizedSelection.normalized.length >= 3) {
+    const partialMatches = items.filter((world) => (
+      normalizeLookupText(world.worldId).includes(normalizedSelection.normalized)
+      || normalizeLookupText(world.displayName).includes(normalizedSelection.normalized)
+    ));
+
+    if (partialMatches.length === 1) {
+      [selectedWorld] = partialMatches;
+      matchedBy = 'partial';
+    } else if (partialMatches.length > 1) {
+      return buildSelectionRetryContract('ambiguous', normalizedSelection, items, partialMatches);
+    }
+  }
+
+  if (!selectedWorld) {
+    return buildSelectionRetryContract('no_match', normalizedSelection, items);
+  }
+
+  return {
+    status: 'selected',
+    selection: {
+      input: normalizedSelection.text || null,
+      matchedBy,
+      worldId: selectedWorld.worldId,
+      displayName: selectedWorld.displayName,
+    },
+    selectedWorld,
+    candidateWorlds: items,
+    orchestration: {
+      stage: 'post_setup_world_selected',
+      system: 'Confirm the resolved world choice before fetching detail and explaining the required fields.',
+      user: `I matched the user choice to ${selectedWorld.displayName} [${selectedWorld.worldId}]. Confirm that this is the world we will use next.`,
+      confirmation: `Confirmed world: ${selectedWorld.displayName} [${selectedWorld.worldId}].`,
+      followUp: 'Fetch the selected world detail and explain the required fields one by one before join-check.',
+    },
+  };
+}
+
+function buildFieldStepPrompt(field = {}, index = 0, total = 1) {
+  const examples = Array.isArray(field.examples) && field.examples.length > 0
+    ? ` Example: ${field.examples.map((example) => quoteExample(example)).join(' or ')}.`
+    : '';
+  const description = sentenceCase(
+    field.description || `Provide ${field.label} so the world can evaluate the profile`,
+    'Provide this field so the world can evaluate the profile.',
+  );
+
+  return `Step ${index + 1} of ${total}: ${field.label}. ${description}${examples}`;
+}
+
+export function buildRequiredFieldExplanation(worldDetail = {}) {
+  const detail = normalizeWorldDetail(worldDetail);
+  const requiredFields = detail.requiredFields;
+  const optionalFields = detail.optionalFields;
+  const requiredFieldLabels = requiredFields.map((field) => field.label);
+  const optionalFieldLabels = optionalFields.map((field) => field.label);
+  const summary = requiredFields.length > 0
+    ? `To join ${detail.displayName}, I need ${requiredFields.length} required field${requiredFields.length === 1 ? '' : 's'}: ${joinAsNaturalLanguage(requiredFieldLabels)}.`
+    : `${detail.displayName} does not require any mandatory profile fields before join-check.`;
+  const steps = requiredFields.map((field, index) => ({
+    step: index + 1,
+    fieldId: field.fieldId,
+    label: field.label,
+    prompt: buildFieldStepPrompt(field, index, requiredFields.length),
+    description: field.description,
+    examples: field.examples,
+    constraints: field.constraints,
+  }));
+  const optionalContextSummary = optionalFieldLabels.length > 0
+    ? `Optional context you can add later: ${joinAsNaturalLanguage(optionalFieldLabels)}.`
+    : null;
+  const nextInstruction = steps[0]?.prompt || 'All required fields are already explained. You can move to join-check.';
+
+  return {
+    status: 'ready',
+    stage: 'post_setup_world_requirements',
+    worldId: detail.worldId,
+    displayName: detail.displayName,
+    requiredFieldCount: detail.requiredFieldCount,
+    optionalFieldCount: detail.optionalFieldCount,
+    summary,
+    steps,
+    hints: detail.hints,
+    optionalContextSummary,
+    nextAction: detail.nextAction,
+    orchestration: {
+      stage: 'post_setup_world_requirements',
+      system: 'Confirm the selected world, explain its required fields in plain language, and collect them one at a time before join-check.',
+      confirmation: `Confirmed world: ${detail.displayName} [${detail.worldId}].`,
+      user: [summary, nextInstruction, optionalContextSummary].filter(Boolean).join('\n\n'),
+      followUp: requiredFields.length > 1
+        ? `After the user answers ${steps[0].label}, continue with the remaining required fields in order, then call join-check.`
+        : (requiredFields.length === 1
+          ? 'After the user answers the required field, call join-check.'
+          : 'No required fields remain. Call join-check now.'),
+    },
+  };
+}
+
+function buildFieldLookup(worldDetail = {}) {
+  const detail = normalizeWorldDetail(worldDetail);
+  return new Map(
+    [...detail.requiredFields, ...detail.optionalFields].map((field) => [field.fieldId, field]),
+  );
+}
+
+function selectPromptFields(joinCheck = {}, worldDetail = {}, maxFieldsPerStep = 1) {
+  if (joinCheck.accepted) return [];
+
+  const fieldLookup = buildFieldLookup(worldDetail);
+  const orderedMissingFields = Array.isArray(joinCheck.missingFieldGuidance?.orderedMissingFields)
+    && joinCheck.missingFieldGuidance.orderedMissingFields.length > 0
+    ? joinCheck.missingFieldGuidance.orderedMissingFields
+    : (Array.isArray(joinCheck.missingFields) ? joinCheck.missingFields : []);
+
+  return orderedMissingFields.slice(0, Math.max(1, maxFieldsPerStep)).map((field, index) => {
+    const detailField = fieldLookup.get(field.fieldId) || {};
+    return normalizeField(
+      {
+        ...detailField,
+        ...field,
+        description: normalizeText(field.description, detailField.description || null),
+        examples: Array.isArray(detailField.examples) ? detailField.examples : field.examples,
+        constraints: detailField.constraints || field.constraints,
+      },
+      index,
+      { required: true },
+    );
+  });
+}
+
+function buildProfileFieldPrompt(field = {}, index = 0, total = 1) {
+  const examples = Array.isArray(field.examples) && field.examples.length > 0
+    ? ` Example: ${field.examples.map((example) => quoteExample(example)).join(' or ')}.`
+    : '';
+  const description = sentenceCase(
+    field.description || `Provide ${field.label} so the world can evaluate the profile`,
+    'Provide this field so the world can evaluate the profile.',
+  );
+  const prefix = total > 1 ? `${index + 1}. ` : '';
+
+  return `${prefix}${field.label}. ${description}${examples}`;
+}
+
+function listProvidedRequiredFieldIds(worldDetail = {}, profile = {}, missingFieldIds = []) {
+  const missingSet = new Set(normalizeStringList(missingFieldIds));
+  return normalizeWorldDetail(worldDetail).requiredFields
+    .filter((field) => !missingSet.has(field.fieldId) && !isEmptyProfileValue(profile[field.fieldId]))
+    .map((field) => field.fieldId);
+}
+
+function buildProfileCollectionFollowUp(promptFields = []) {
+  if (promptFields.length === 0) {
+    return 'The current profile is already eligible. Continue with the next world step without restarting profile collection.';
+  }
+
+  const labels = promptFields.map((field) => field.label);
+  if (promptFields.length === 1) {
+    return `After the user answers ${labels[0]}, merge it into the saved profile draft and re-run join-check before asking anything else.`;
+  }
+
+  return `After the user answers ${joinAsNaturalLanguage(labels)}, merge those fields into the saved profile draft and re-run join-check before asking anything else.`;
+}
+
+export function buildWorldProfileCollectionFlow({
+  worldDetail = {},
+  joinCheck = {},
+  profile = {},
+  maxFieldsPerStep = 1,
+} = {}) {
+  const detail = normalizeWorldDetail(worldDetail);
+  const normalizedJoinCheck = normalizeJoinCheckResponse(joinCheck, {
+    worldId: detail.worldId,
+    profile,
+  });
+  const promptLimit = Math.max(1, normalizeInteger(maxFieldsPerStep, 1));
+  const promptFields = selectPromptFields(normalizedJoinCheck, detail, promptLimit);
+  const promptFieldIds = promptFields.map((field) => field.fieldId);
+  const providedRequiredFieldIds = listProvidedRequiredFieldIds(
+    detail,
+    normalizedJoinCheck.normalizedProfile,
+    normalizedJoinCheck.missingFieldGuidance.orderedMissingFieldIds,
+  );
+  const providedRequiredLabels = detail.requiredFields
+    .filter((field) => providedRequiredFieldIds.includes(field.fieldId))
+    .map((field) => field.label);
+  const optionalFieldLabels = detail.optionalFields.map((field) => field.label);
+  const remainingCount = normalizedJoinCheck.missingFieldGuidance.remainingRequiredFieldCount;
+  const summary = normalizedJoinCheck.accepted
+    ? `All required fields for ${detail.displayName} are currently present.`
+    : `${remainingCount} required field${remainingCount === 1 ? '' : 's'} still need to be collected for ${detail.displayName}.`;
+  const savedSummary = providedRequiredLabels.length > 0
+    ? `Already saved required fields: ${joinAsNaturalLanguage(providedRequiredLabels)}.`
+    : 'No required fields are saved yet.';
+  const promptSummary = promptFields.length === 0
+    ? null
+    : (promptFields.length === 1
+      ? 'Ask the user for this required field next:'
+      : `Ask the user for these ${promptFields.length} required fields next, and accept them in one reply if convenient:`);
+  const promptBody = promptFields.length === 0
+    ? null
+    : promptFields.map((field, index) => buildProfileFieldPrompt(field, index, promptFields.length)).join('\n');
+  const optionalContextSummary = optionalFieldLabels.length > 0
+    ? `Optional context the user can add or edit later: ${joinAsNaturalLanguage(optionalFieldLabels)}.`
+    : null;
+  const revalidationMode = normalizedJoinCheck.accepted
+    ? 'complete'
+    : (promptFields.length > 1 ? 'after_current_batch' : 'after_each_reply');
+
+  return {
+    accepted: normalizedJoinCheck.accepted,
+    status: normalizedJoinCheck.status,
+    source: 'product_shell',
+    worldId: detail.worldId,
+    displayName: detail.displayName,
+    profile: normalizedJoinCheck.normalizedProfile,
+    promptFields,
+    promptFieldIds,
+    providedRequiredFieldIds,
+    remainingRequiredFieldCount: remainingCount,
+    nextAction: normalizedJoinCheck.nextAction,
+    revalidationCheckpoint: {
+      mode: revalidationMode,
+      promptFieldIds,
+    },
+    orchestration: {
+      stage: 'post_setup_world_profile_collection',
+      system:
+        'Use backend join-check guidance as the source of truth for the next required field prompt. After every user reply or the current batch checkpoint, merge the updates into the saved profile draft and re-run join-check.',
+      confirmation: `Confirmed world: ${detail.displayName} [${detail.worldId}].`,
+      user: [summary, savedSummary, promptSummary, promptBody, optionalContextSummary].filter(Boolean).join('\n\n'),
+      followUp: buildProfileCollectionFollowUp(promptFields),
+    },
+  };
+}
+
+export function buildWorldJoinOutcomeOrchestration({ worldDetail = {}, joinResult = {} } = {}) {
+  const detail = normalizeWorldDetail(worldDetail);
+  const membershipStatus = normalizeText(
+    joinResult.membershipStatus || joinResult.membership?.status,
+    'unknown',
+  );
+  const joinSummary = joinResult.nextStageSummary?.summary
+    ? sentenceCase(joinResult.nextStageSummary.summary, '')
+    : null;
+
+  return {
+    stage: 'world_join_result',
+    status: membershipStatus,
+    system:
+      'The backend already resolved the world join result. Reflect the authoritative membership outcome before any search, candidate review, or live-session follow-up.',
+    confirmation: `World membership in ${detail.displayName} [${detail.worldId}] is ${membershipStatus}.`,
+    user: membershipStatus === 'active'
+      ? ['Joined ' + detail.displayName + ' successfully. World membership is active.', joinSummary].filter(Boolean).join(' ')
+      : `The join result for ${detail.displayName} is ${membershipStatus}.`,
+    followUp: membershipStatus === 'active'
+      ? 'Use backend-authored next-stage summary and candidate-delivery payloads for the next world step.'
+      : 'Do not continue to world-member-only follow-up until membership becomes active.',
+  };
+}
+
+export function buildResolvedWorldSelectionOrchestration({
+  selection = null,
+  profileCollectionFlow = null,
+} = {}) {
+  const selectionOrchestration = selection?.orchestration && typeof selection.orchestration === 'object' && !Array.isArray(selection.orchestration)
+    ? selection.orchestration
+    : null;
+  const profileOrchestration = profileCollectionFlow?.orchestration && typeof profileCollectionFlow.orchestration === 'object' && !Array.isArray(profileCollectionFlow.orchestration)
+    ? profileCollectionFlow.orchestration
+    : null;
+
+  if (!profileOrchestration) return selectionOrchestration;
+
+  return {
+    stage: normalizeText(profileOrchestration.stage, normalizeText(selectionOrchestration?.stage, null)),
+    system: normalizeText(profileOrchestration.system, normalizeText(selectionOrchestration?.system, null)),
+    confirmation: normalizeText(
+      profileOrchestration.confirmation,
+      normalizeText(selectionOrchestration?.confirmation, null),
+    ),
+    user: [
+      normalizeText(profileOrchestration.confirmation, null),
+      normalizeText(profileOrchestration.user, null),
+    ].filter(Boolean).join('\n\n'),
+    followUp: normalizeText(
+      profileOrchestration.followUp,
+      normalizeText(selectionOrchestration?.followUp, null),
+    ),
+  };
+}
+
+export function buildCandidateDeliverySummary(candidateFeed = {}, { worldDetail = null, limit = null } = {}) {
+  const detail = worldDetail ? normalizeWorldDetail(worldDetail) : null;
+  const normalizedFeed = normalizeCandidateFeedResponse(candidateFeed, {
+    worldId: detail?.worldId || candidateFeed.worldId || null,
+    agentId: candidateFeed.agentId || null,
+  });
+  const summaryLimit = Math.max(
+    1,
+    normalizeInteger(limit, normalizedFeed.candidates.length || normalizedFeed.totalCandidates || 1),
+  );
+  const displayName = detail?.displayName || normalizedFeed.worldId || 'the selected world';
+  const candidateSummaries = normalizedFeed.candidates.slice(0, summaryLimit).map((candidate, index) => {
+    const name = candidate.profileSummary.displayName || `Candidate ${index + 1}`;
+    const requiredFieldSummary = summarizeProfileFields(candidate.profileSummary.requiredFields);
+    const optionalFieldSummary = summarizeProfileFields(candidate.profileSummary.optionalFields);
+    const compatibilitySummary = candidate.compatibilitySignals
+      .map((signal) => sentenceCase(signal.summary, ''))
+      .filter(Boolean);
+    const deliveryReasonSummary = sentenceCase(candidate.deliveryReason.summary, '');
+    const scoreSummary = candidate.score == null
+      ? null
+      : `Score ${candidate.score}${candidate.rank == null ? '' : `, rank ${candidate.rank}`}.`;
+    const summary = [
+      candidate.profileSummary.headline ? `${name}: ${candidate.profileSummary.headline}.` : `${name}.`,
+      requiredFieldSummary.length > 0 ? `Required profile fields: ${requiredFieldSummary.join('; ')}.` : null,
+      optionalFieldSummary.length > 0 ? `Optional context: ${optionalFieldSummary.join('; ')}.` : null,
+      compatibilitySummary.length > 0 ? compatibilitySummary.join(' ') : null,
+      deliveryReasonSummary || null,
+      scoreSummary,
+    ].filter(Boolean).join(' ');
+
+    return {
+      candidateId: candidate.candidateId,
+      sourceMembershipId: candidate.sourceMembershipId,
+      displayName: name,
+      headline: candidate.profileSummary.headline,
+      rank: candidate.rank,
+      score: candidate.score,
+      requiredFieldSummary,
+      optionalFieldSummary,
+      compatibilitySummary,
+      deliveryReasonSummary: deliveryReasonSummary || null,
+      expiresAt: candidate.expiresAt,
+      summary,
+    };
+  });
+  const deliveredCandidateCount = candidateSummaries.length;
+  const totalCandidateCount = Math.max(normalizedFeed.totalCandidates, deliveredCandidateCount);
+  const remainingCandidateCount = Math.max(totalCandidateCount - deliveredCandidateCount, 0);
+  const heading = deliveredCandidateCount > 0
+    ? `${displayName} has ${deliveredCandidateCount} candidate profile ${deliveredCandidateCount === 1 ? 'summary' : 'summaries'} ready for review now.`
+    : `No candidate profile summaries are ready for review in ${displayName} yet.`;
+  const promptBody = deliveredCandidateCount > 0
+    ? candidateSummaries.map((summary, index) => buildCandidateDeliverySummaryLine(summary, index)).join('\n\n')
+    : 'No candidates are currently available from the active-membership feed.';
+
+  return {
+    status: deliveredCandidateCount > 0 ? 'candidate_summary_ready' : 'candidate_summary_pending',
+    deliveredCandidateCount,
+    totalCandidateCount,
+    remainingCandidateCount,
+    candidateSummaries,
+    nextAction: deliveredCandidateCount > 0
+      ? normalizedFeed.nextAction
+      : 'wait_for_more_candidates',
+    orchestration: {
+      stage: 'post_join_candidate_delivery',
+      system:
+        'Use the backend-authored candidate summaries already attached to this payload. Do not invent additional candidate-delivery business text locally.',
+      confirmation: `Candidate review payload for ${displayName} [${normalizedFeed.worldId}].`,
+      user: [heading, promptBody].filter(Boolean).join('\n\n'),
+      followUp: deliveredCandidateCount > 0
+        ? (remainingCandidateCount > 0
+          ? `Share these ${deliveredCandidateCount} candidate summaries first. If the user wants more, continue with the remaining ${remainingCandidateCount} candidate${remainingCandidateCount === 1 ? '' : 's'} from the same feed before requesting a live session.`
+          : 'Share these candidate summaries and ask whether the user wants to review them further or continue toward a live session later.')
+        : 'Tell the user candidate delivery can be retried later through the same backend-authored world flow.',
+    },
+  };
+}
+
+export function buildResolvedWorldJoinOrchestration({
+  joinResult = null,
+  candidateDelivery = null,
+} = {}) {
+  const joinOrchestration = joinResult?.orchestration && typeof joinResult.orchestration === 'object' && !Array.isArray(joinResult.orchestration)
+    ? joinResult.orchestration
+    : null;
+  const candidateOrchestration = candidateDelivery?.orchestration && typeof candidateDelivery.orchestration === 'object' && !Array.isArray(candidateDelivery.orchestration)
+    ? candidateDelivery.orchestration
+    : null;
+
+  if (!candidateOrchestration) return joinOrchestration;
+
+  return {
+    stage: normalizeText(candidateOrchestration.stage, normalizeText(joinOrchestration?.stage, null)),
+    system: normalizeText(candidateOrchestration.system, normalizeText(joinOrchestration?.system, null)),
+    confirmation: normalizeText(
+      joinOrchestration?.confirmation,
+      normalizeText(candidateOrchestration.confirmation, null),
+    ),
+    user: [
+      normalizeText(joinOrchestration?.user, normalizeText(joinOrchestration?.confirmation, null)),
+      normalizeText(candidateOrchestration.user, null),
+    ].filter(Boolean).join('\n\n'),
+    followUp: normalizeText(
+      candidateOrchestration.followUp,
+      normalizeText(joinOrchestration?.followUp, null),
+    ),
+  };
+}