@xfxstudio/claworld 0.1.0

package/src/product-shell/matching/matchmaking-service.js

@@ -0,0 +1,340 @@
+import { buildCandidateFeed, normalizeCandidateFeedLimit, projectCandidateFeedModel } from '../contracts/candidate-feed.js';
+import { WORLD_ACTIONS } from '../worlds/world-authorization.js';
+
+const DATING_DEMO_SCORING_SIGNALS = Object.freeze([
+  {
+    signalId: 'intent_exact_match',
+    label: 'Intent Exact Match',
+    weight: 50,
+    sourceFieldIds: ['intent'],
+    summary: 'Add 50 points when both active memberships declare the same normalized intent.',
+  },
+  {
+    signalId: 'same_location',
+    label: 'Same Location',
+    weight: 30,
+    sourceFieldIds: ['location'],
+    summary: 'Add 30 points when both active memberships declare the same normalized location.',
+  },
+  {
+    signalId: 'shared_interests',
+    label: 'Shared Interests',
+    weight: 20,
+    sourceFieldIds: ['interests'],
+    summary: 'Add 10 points per shared normalized interest, capped at 20 points.',
+  },
+]);
+
+function createConfigurationError() {
+  const error = new Error('membership_store_unavailable');
+  error.code = 'membership_store_unavailable';
+  error.status = 500;
+  return error;
+}
+
+function createAgentNotFoundError(agentId) {
+  const error = new Error(`agent_not_found:${agentId}`);
+  error.code = 'agent_not_found';
+  error.status = 404;
+  return error;
+}
+
+function createInvalidCandidateFeedRequestError(fieldId, message = `${fieldId} is required`) {
+  const error = new Error(`invalid_candidate_feed_request:${fieldId}`);
+  error.code = 'invalid_candidate_feed_request';
+  error.status = 400;
+  error.responseBody = {
+    error: error.code,
+    message: 'candidate feed request is missing required fields',
+    fieldErrors: [
+      {
+        fieldId,
+        message,
+      },
+    ],
+  };
+  return error;
+}
+
+function createCandidateFeedMembershipNotActiveError(worldId, agentId) {
+  const error = new Error(`candidate_feed_membership_not_active:${worldId}:${agentId}`);
+  error.code = 'candidate_feed_membership_not_active';
+  error.status = 409;
+  error.responseBody = {
+    error: error.code,
+    message: 'agent must have an active world membership before requesting candidate feed',
+    worldId,
+    agentId,
+    requiredMembershipStatus: 'active',
+  };
+  return error;
+}
+
+function normalizeAgentId(agentId) {
+  const normalized = String(agentId || '').trim();
+  return normalized || null;
+}
+
+function normalizeText(value) {
+  return String(value || '').trim().toLowerCase();
+}
+
+function normalizeStringList(value) {
+  if (!Array.isArray(value)) return [];
+  return [...new Set(
+    value
+      .map((item) => normalizeText(item))
+      .filter(Boolean),
+  )].sort((left, right) => left.localeCompare(right));
+}
+
+function projectScoringSignals(worldId) {
+  if (worldId !== 'dating-demo-world') return [];
+  return DATING_DEMO_SCORING_SIGNALS.map((signal) => ({ ...signal }));
+}
+
+function buildStrategy(world) {
+  return {
+    worldId: world.worldId,
+    mode: world.matching.mode,
+    cadence: world.matching.cadence,
+    strategySummary: world.matching.strategySummary,
+    candidateSources: world.matching.candidateSources,
+    inputFields: world.joinSchema.requiredFields.map((field) => field.fieldId),
+    candidateFeedModel: projectCandidateFeedModel(world),
+    scoringSignals: projectScoringSignals(world.worldId),
+    status: world.worldId === 'dating-demo-world' ? 'candidate_scoring_ready' : 'scaffold_ready',
+  };
+}
+
+function buildInterestBreakdown(requesterInterests, candidateInterests) {
+  const sharedValues = requesterInterests.filter((interest) => candidateInterests.includes(interest));
+  const contribution = Math.min(sharedValues.length * 10, 20);
+
+  return {
+    signalId: 'shared_interests',
+    label: 'Shared Interests',
+    weight: 20,
+    sourceFieldIds: ['interests'],
+    matched: sharedValues.length > 0,
+    requesterValue: requesterInterests,
+    candidateValue: candidateInterests,
+    sharedValues,
+    overlapCount: sharedValues.length,
+    contribution,
+  };
+}
+
+function buildDatingDemoScoreDetails(viewerMembership, candidateMembership) {
+  const viewerIntent = normalizeText(viewerMembership.profileSnapshot?.intent);
+  const candidateIntent = normalizeText(candidateMembership.profileSnapshot?.intent);
+  const viewerLocation = normalizeText(viewerMembership.profileSnapshot?.location);
+  const candidateLocation = normalizeText(candidateMembership.profileSnapshot?.location);
+  const viewerInterests = normalizeStringList(viewerMembership.profileSnapshot?.interests);
+  const candidateInterests = normalizeStringList(candidateMembership.profileSnapshot?.interests);
+
+  const scoreBreakdown = [
+    {
+      signalId: 'intent_exact_match',
+      label: 'Intent Exact Match',
+      weight: 50,
+      sourceFieldIds: ['intent'],
+      matched: viewerIntent !== '' && viewerIntent === candidateIntent,
+      requesterValue: viewerIntent,
+      candidateValue: candidateIntent,
+      contribution: viewerIntent !== '' && viewerIntent === candidateIntent ? 50 : 0,
+    },
+    {
+      signalId: 'same_location',
+      label: 'Same Location',
+      weight: 30,
+      sourceFieldIds: ['location'],
+      matched: viewerLocation !== '' && viewerLocation === candidateLocation,
+      requesterValue: viewerLocation,
+      candidateValue: candidateLocation,
+      contribution: viewerLocation !== '' && viewerLocation === candidateLocation ? 30 : 0,
+    },
+    buildInterestBreakdown(viewerInterests, candidateInterests),
+  ];
+
+  return {
+    joinedAt: candidateMembership.joinedAt,
+    score: scoreBreakdown.reduce((sum, signal) => sum + signal.contribution, 0),
+    scoreBreakdown,
+    scoringInputs: {
+      requester: {
+        intent: viewerIntent,
+        location: viewerLocation,
+        interests: viewerInterests,
+      },
+      candidate: {
+        intent: candidateIntent,
+        location: candidateLocation,
+        interests: candidateInterests,
+      },
+      overlap: {
+        sharedInterests: scoreBreakdown[2].sharedValues,
+      },
+    },
+  };
+}
+
+function compareRankedCandidates(left, right) {
+  if (right.score !== left.score) return right.score - left.score;
+
+  const rightSharedInterestCount = right.scoringInputs.overlap.sharedInterests.length;
+  const leftSharedInterestCount = left.scoringInputs.overlap.sharedInterests.length;
+  if (rightSharedInterestCount !== leftSharedInterestCount) {
+    return rightSharedInterestCount - leftSharedInterestCount;
+  }
+
+  if (left.joinedAt !== right.joinedAt) {
+    return String(left.joinedAt).localeCompare(String(right.joinedAt));
+  }
+
+  return String(left.sourceMembershipId).localeCompare(String(right.sourceMembershipId));
+}
+
+function buildViewerContext({ world, membershipStore, normalizedAgentId, worldAuthorizationService }) {
+  const viewerAgent = membershipStore.getAgent(normalizedAgentId);
+  if (!viewerAgent) {
+    throw createAgentNotFoundError(normalizedAgentId);
+  }
+
+  const authorization = worldAuthorizationService.evaluateWorldAction({
+    worldId: world.worldId,
+    actorAgentId: normalizedAgentId,
+    action: WORLD_ACTIONS.VIEW_CANDIDATE_FEED,
+  });
+
+  if (!authorization.allowed || authorization.membership?.status !== 'active') {
+    throw createCandidateFeedMembershipNotActiveError(world.worldId, normalizedAgentId);
+  }
+
+  return {
+    viewerAgent,
+    viewerMembership: authorization.membership,
+  };
+}
+
+function buildBaseFeed({ world, membershipStore, normalizedAgentId, limit, worldAuthorizationService }) {
+  const { viewerAgent, viewerMembership } = buildViewerContext({
+    world,
+    membershipStore,
+    normalizedAgentId,
+    worldAuthorizationService,
+  });
+  const activeMemberships = membershipStore.listMemberships({
+    worldId: world.worldId,
+    status: 'active',
+  });
+  const normalizedLimit = normalizeCandidateFeedLimit(limit);
+  const nowMs = typeof membershipStore.nowMs === 'function' ? membershipStore.nowMs() : Date.now();
+  const baseFeed = buildCandidateFeed({
+    world,
+    viewerMembership,
+    viewerAgent,
+    candidateMemberships: activeMemberships,
+    getAgent: (candidateAgentId) => membershipStore.getAgent(candidateAgentId),
+    nowMs,
+    limit: activeMemberships.length,
+  });
+
+  return {
+    viewerMembership,
+    activeMemberships,
+    normalizedLimit,
+    baseFeed,
+  };
+}
+
+function buildDatingDemoFeed({ world, membershipStore, normalizedAgentId, limit, worldAuthorizationService }) {
+  const { viewerMembership, activeMemberships, normalizedLimit, baseFeed } = buildBaseFeed({
+    world,
+    membershipStore,
+    normalizedAgentId,
+    limit,
+    worldAuthorizationService,
+  });
+  const membershipById = new Map(activeMemberships.map((membership) => [membership.membershipId, membership]));
+  const rankedCandidates = baseFeed.candidates
+    .map((candidate) => {
+      const candidateMembership = membershipById.get(candidate.sourceMembershipId);
+      return {
+        ...candidate,
+        ...buildDatingDemoScoreDetails(viewerMembership, candidateMembership),
+      };
+    })
+    .sort(compareRankedCandidates);
+
+  const candidates = rankedCandidates
+    .slice(0, normalizedLimit)
+    .map((candidate, index) => ({
+      ...candidate,
+      rank: index + 1,
+    }));
+
+  return {
+    ...baseFeed,
+    agentId: normalizedAgentId,
+    limit: normalizedLimit,
+    candidateSource: 'active_memberships',
+    strategy: buildStrategy(world),
+    totalCandidates: rankedCandidates.length,
+    candidates,
+  };
+}
+
+export function createMatchmakingService({ worldService, worldAuthorizationService, store = null } = {}) {
+  function assertStore() {
+    if (!store) throw createConfigurationError();
+    return store;
+  }
+
+  return {
+    describeStrategy(worldId) {
+      const world = worldService.requireWorld(worldId);
+      return buildStrategy(world);
+    },
+    listCandidateFeed({ worldId, agentId, limit } = {}) {
+      const world = worldService.requireWorld(worldId);
+      const membershipStore = assertStore();
+      const normalizedAgentId = normalizeAgentId(agentId);
+
+      if (!normalizedAgentId) {
+        throw createInvalidCandidateFeedRequestError('agentId');
+      }
+
+      if (world.worldId === 'dating-demo-world') {
+        return buildDatingDemoFeed({
+          world,
+          membershipStore,
+          normalizedAgentId,
+          limit,
+          worldAuthorizationService,
+        });
+      }
+
+      const { normalizedLimit, baseFeed } = buildBaseFeed({
+        world,
+        membershipStore,
+        normalizedAgentId,
+        limit,
+        worldAuthorizationService,
+      });
+
+      return {
+        ...baseFeed,
+        agentId: normalizedAgentId,
+        limit: normalizedLimit,
+        candidateSource: 'active_memberships',
+        strategy: buildStrategy(world),
+        totalCandidates: baseFeed.candidates.length,
+        candidates: baseFeed.candidates.slice(0, normalizedLimit),
+      };
+    },
+    listCandidates(options = {}) {
+      return this.listCandidateFeed(options);
+    },
+  };
+}

package/src/product-shell/membership/membership-service.js

@@ -0,0 +1,277 @@
+import {
+  buildWorldJoinOutcomeOrchestration,
+  buildWorldProfileCollectionFlow,
+} from '../contracts/world-orchestration.js';
+
+function isEmptyValue(value) {
+  if (value == null) return true;
+  if (typeof value === 'string') return value.trim() === '';
+  if (Array.isArray(value)) return value.length === 0;
+  return false;
+}
+
+function projectMissingField(field = {}) {
+  return {
+    fieldId: field.fieldId,
+    label: field.label,
+    description: field.description,
+  };
+}
+
+function createConfigurationError() {
+  const error = new Error('membership_store_unavailable');
+  error.code = 'membership_store_unavailable';
+  error.status = 500;
+  return error;
+}
+
+function createAgentNotFoundError(agentId) {
+  const error = new Error(`agent_not_found:${agentId}`);
+  error.code = 'agent_not_found';
+  error.status = 404;
+  return error;
+}
+
+function createInvalidJoinRequestError(fieldId, message = `${fieldId} is required`) {
+  const error = new Error(`invalid_join_request:${fieldId}`);
+  error.code = 'invalid_join_request';
+  error.status = 400;
+  error.responseBody = {
+    error: error.code,
+    message: 'join request is missing required fields',
+    fieldErrors: [
+      {
+        fieldId,
+        message,
+      },
+    ],
+  };
+  return error;
+}
+
+function createMembershipNotEligibleError(joinCheck) {
+  const error = new Error('membership_not_eligible');
+  error.code = 'membership_not_eligible';
+  error.status = 422;
+  error.responseBody = {
+    error: error.code,
+    message: 'profile does not satisfy world join requirements',
+    joinCheck,
+    profileCollectionFlow: joinCheck.profileCollectionFlow || null,
+  };
+  return error;
+}
+
+function createJoinNotEligibleError(joinCheck) {
+  const error = new Error('world_join_not_eligible');
+  error.code = 'world_join_not_eligible';
+  error.status = 422;
+  error.responseBody = {
+    error: error.code,
+    message: 'profile does not satisfy world join requirements',
+    membershipStatus: 'inactive',
+    worldId: joinCheck.worldId,
+    missingFields: joinCheck.missingFields,
+    nextMissingField: joinCheck.nextMissingField,
+    missingFieldGuidance: joinCheck.missingFieldGuidance,
+    normalizedProfile: joinCheck.normalizedProfile,
+    nextAction: joinCheck.nextAction,
+    joinCheck,
+    profileCollectionFlow: joinCheck.profileCollectionFlow || null,
+  };
+  return error;
+}
+
+function normalizeAgentId(agentId) {
+  const normalized = String(agentId || '').trim();
+  return normalized || null;
+}
+
+function normalizeProfileSnapshot(...candidates) {
+  for (const candidate of candidates) {
+    if (candidate && typeof candidate === 'object' && !Array.isArray(candidate)) {
+      return candidate;
+    }
+  }
+  return {};
+}
+
+function buildNextStageSummary(world) {
+  const matchingSummary = world.matching.strategySummary
+    || `The world uses ${world.matching.mode} matching before session handoff.`;
+  const sessionSummary = `Matched agents then enter a ${world.sessionTemplate.mode} session with up to ${world.sessionTemplate.maxTurns} turns.`;
+
+  return {
+    stage: 'matchmaking',
+    summary: `${matchingSummary} ${sessionSummary}`.trim(),
+    matchingMode: world.matching.mode,
+    matchingCadence: world.matching.cadence,
+    sessionMode: world.sessionTemplate.mode,
+    maxTurns: world.sessionTemplate.maxTurns,
+    turnTimeoutMs: world.sessionTemplate.turnTimeoutMs,
+  };
+}
+
+export function createMembershipService({ worldService, store = null } = {}) {
+  function assertStore() {
+    if (!store) throw createConfigurationError();
+    return store;
+  }
+
+  return {
+    evaluateJoin({ worldId, profile = {}, maxFieldsPerStep = 1 } = {}) {
+      const world = worldService.requireWorld(worldId);
+      const normalizedProfile = profile && typeof profile === 'object' ? profile : {};
+      const orderedMissingFields = world.joinSchema.requiredFields.filter((field) =>
+        isEmptyValue(normalizedProfile[field.fieldId]),
+      );
+      const missingFields = orderedMissingFields.map((field) => projectMissingField(field));
+      const nextMissingField = missingFields[0] || null;
+
+      const joinCheck = {
+        worldId: world.worldId,
+        accepted: missingFields.length === 0,
+        status: missingFields.length === 0 ? 'eligible' : 'needs_profile',
+        missingFields,
+        nextMissingField,
+        missingFieldGuidance: {
+          mode: nextMissingField ? 'ordered_required_fields' : 'complete',
+          orderedMissingFields: missingFields,
+          orderedMissingFieldIds: missingFields.map((field) => field.fieldId),
+          nextMissingField,
+          remainingRequiredFieldCount: missingFields.length,
+        },
+        normalizedProfile,
+        nextAction:
+          missingFields.length === 0 ? 'join_world_when_membership_persistence_exists' : 'collect_missing_profile_fields',
+      };
+
+      const worldDetail = worldService.describeWorldDetail(world.worldId);
+      return {
+        ...joinCheck,
+        profileCollectionFlow: buildWorldProfileCollectionFlow({
+          worldDetail,
+          joinCheck,
+          profile: normalizedProfile,
+          maxFieldsPerStep,
+        }),
+      };
+    },
+    async createMembership({ worldId, agentId, profileSnapshot } = {}) {
+      worldService.requireWorld(worldId);
+      const membershipStore = assertStore();
+      const normalizedAgentId = normalizeAgentId(agentId);
+      if (!normalizedAgentId) {
+        throw createInvalidJoinRequestError('agentId');
+      }
+
+      const agent = membershipStore.getAgent(normalizedAgentId);
+
+      if (!agent) {
+        throw createAgentNotFoundError(normalizedAgentId);
+      }
+
+      const normalizedProfileSnapshot = normalizeProfileSnapshot(profileSnapshot, agent.profile);
+      const joinCheck = this.evaluateJoin({
+        worldId,
+        profile: normalizedProfileSnapshot,
+      });
+
+      if (!joinCheck.accepted) {
+        throw createMembershipNotEligibleError(joinCheck);
+      }
+
+      const existingMembership = membershipStore.listMemberships({
+        worldId,
+        agentId: normalizedAgentId,
+      })[0] || null;
+
+      if (existingMembership) {
+        return { membership: existingMembership, created: false };
+      }
+
+      const membership = await membershipStore.createMembership({
+        worldId,
+        agentId: normalizedAgentId,
+        status: 'joined',
+        profileSnapshot: joinCheck.normalizedProfile,
+      });
+
+      return { membership, created: true };
+    },
+    async joinWorld({ worldId, agentId, profile, profileSnapshot, maxFieldsPerStep = 1 } = {}) {
+      const world = worldService.requireWorld(worldId);
+      const membershipStore = assertStore();
+      const normalizedAgentId = normalizeAgentId(agentId);
+
+      if (!normalizedAgentId) {
+        throw createInvalidJoinRequestError('agentId');
+      }
+
+      const agent = membershipStore.getAgent(normalizedAgentId);
+      if (!agent) {
+        throw createAgentNotFoundError(normalizedAgentId);
+      }
+
+      const effectiveProfile = normalizeProfileSnapshot(profile, profileSnapshot, agent.profile);
+      const joinCheck = this.evaluateJoin({
+        worldId: world.worldId,
+        profile: effectiveProfile,
+        maxFieldsPerStep,
+      });
+
+      if (!joinCheck.accepted) {
+        throw createJoinNotEligibleError(joinCheck);
+      }
+
+      const existingMembership = membershipStore.listMemberships({
+        worldId: world.worldId,
+        agentId: normalizedAgentId,
+      })[0] || null;
+
+      const membership = existingMembership
+        ? await membershipStore.updateMembership(existingMembership.membershipId, {
+          status: 'active',
+          profileSnapshot: joinCheck.normalizedProfile,
+        })
+        : await membershipStore.createMembership({
+          worldId: world.worldId,
+          agentId: normalizedAgentId,
+          status: 'active',
+          profileSnapshot: joinCheck.normalizedProfile,
+        });
+
+      return {
+        membership,
+        membershipStatus: membership.status,
+        created: !existingMembership,
+        nextStageSummary: buildNextStageSummary(world),
+        orchestration: buildWorldJoinOutcomeOrchestration({
+          worldDetail: worldService.describeWorldDetail(world.worldId),
+          joinResult: {
+            membershipStatus: membership.status,
+            membership,
+            nextStageSummary: buildNextStageSummary(world),
+          },
+        }),
+      };
+    },
+    getMembership({ worldId, agentId, includeDisabled = false } = {}) {
+      const normalizedAgentId = normalizeAgentId(agentId);
+      if (!normalizedAgentId) return null;
+      worldService.requireWorld(worldId, { includeDisabled });
+      return assertStore().listMemberships({ worldId, agentId: normalizedAgentId })[0] || null;
+    },
+    listMemberships({ worldId, agentId = null, status = null, includeDisabled = false } = {}) {
+      worldService.requireWorld(worldId, { includeDisabled });
+      return assertStore().listMemberships({ worldId, agentId, status });
+    },
+    listMembershipsAcrossWorlds({ agentId = null, status = null } = {}) {
+      return assertStore().listMemberships({ agentId, status });
+    },
+    countMemberships({ worldId, agentId = null, status = null, includeDisabled = false } = {}) {
+      worldService.requireWorld(worldId, { includeDisabled });
+      return assertStore().countMemberships({ worldId, agentId, status });
+    },
+  };
+}

package/src/product-shell/onboarding/onboarding-routes.js

@@ -0,0 +1,37 @@
+import { authenticateAppTokenRequest } from '../../lib/http-auth.js';
+
+function sendOnboardingError(res, error) {
+  const status = Number.isInteger(error?.status) ? error.status : 500;
+  if (error?.responseBody && typeof error.responseBody === 'object') {
+    return res.status(status).json(error.responseBody);
+  }
+  const code = typeof error?.code === 'string' ? error.code : 'internal_error';
+  return res.status(status).json({ error: code, message: error?.message || code });
+}
+
+export function registerOnboardingRoutes(app, { onboardingService, store = null }) {
+  app.get('/v1/meta/install', (_req, res) => {
+    res.json(onboardingService.getInstallManifest());
+  });
+
+  app.get('/v1/onboarding/plan', (req, res) => {
+    res.json(onboardingService.getFirstRunPlan({ worldId: req.query.worldId }));
+  });
+
+  app.post('/v1/onboarding/activate', (req, res) => {
+    const auth = authenticateAppTokenRequest({ store, req });
+    if (auth.present && !auth.ok) {
+      return res.status(401).json(auth.error);
+    }
+
+    try {
+      const result = onboardingService.activateInstallation({
+        auth,
+        input: req.body || {},
+      });
+      return res.status(result.created ? 201 : 200).json(result);
+    } catch (error) {
+      return sendOnboardingError(res, error);
+    }
+  });
+}