@wibly/internal-manifest 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,6 @@
+# `@wibly/internal-manifest` — Changelog
+
+## 0.1.1 — 2026-05-30
+
+Initial public npm release. Internal runtime dependency of `@wibly/sdk` and
+`@wibly/sdk-testkit` — not a supported direct import surface for game bundles.

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@wibly/internal-manifest",
+  "version": "0.1.1",
+  "description": "Wibly @wibly/internal-manifest",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wibly/wibly"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@wibly/internal-protocol": "0.1.1",
+    "@wibly/internal-shared": "0.1.1",
+    "zod": "^3.25.76"
+  },
+  "peerDependencies": {}
+}

package/src/content-rating.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  isSmutTierCapable,
+  portalContentRatingLabel,
+  safetyFloorFromContentRatingTier,
+} from './content-rating.js';
+
+describe('content-rating mappers', () => {
+  it('maps tiers to safety floors', () => {
+    expect(safetyFloorFromContentRatingTier('none')).toBe('general');
+    expect(safetyFloorFromContentRatingTier('pg13')).toBe('pg13');
+    expect(safetyFloorFromContentRatingTier('mature')).toBe('mature');
+    expect(safetyFloorFromContentRatingTier('extra_smut')).toBe('mature');
+  });
+
+  it('enables smut tier only for extra_smut', () => {
+    expect(isSmutTierCapable('extra_smut')).toBe(true);
+    expect(isSmutTierCapable('mature')).toBe(false);
+  });
+
+  it('labels portal badges', () => {
+    expect(portalContentRatingLabel('none')).toBe('All ages');
+    expect(portalContentRatingLabel('extra_smut')).toBe('Extra Smut');
+  });
+});

package/src/content-rating.ts

@@ -0,0 +1,51 @@
+import type {
+  ContentRatingFloor,
+  ExperienceContentRatingTier,
+} from './manifest.js';
+
+/**
+ * Map the unified Experience content-rating tier to the Safety
+ * pipeline floor (`general` | `pg13` | `mature`).
+ */
+export const safetyFloorFromContentRatingTier = (
+  tier: ExperienceContentRatingTier,
+): ContentRatingFloor => {
+  switch (tier) {
+    case 'none':
+      return 'general';
+    case 'pg13':
+      return 'pg13';
+    case 'mature':
+    case 'extra_smut':
+      return 'mature';
+    default: {
+      const _exhaustive: never = tier;
+      return _exhaustive;
+    }
+  }
+};
+
+/** Whether the User Portal should render the smut-tier selector. */
+export const isSmutTierCapable = (
+  tier: ExperienceContentRatingTier,
+): boolean => tier === 'extra_smut';
+
+/** Human-readable badge label for catalogue and detail pages. */
+export const portalContentRatingLabel = (
+  tier: ExperienceContentRatingTier,
+): string => {
+  switch (tier) {
+    case 'none':
+      return 'All ages';
+    case 'pg13':
+      return 'PG-13';
+    case 'mature':
+      return 'Mature';
+    case 'extra_smut':
+      return 'Extra Smut';
+    default: {
+      const _exhaustive: never = tier;
+      return _exhaustive;
+    }
+  }
+};

package/src/fixtures.ts

@@ -0,0 +1,229 @@
+/**
+ * Canonical manifest fixtures used by the schema and validate-flow
+ * tests. The baseline `validManifestFixture` is a minimal-but-complete
+ * Experience that satisfies every required field and every structural
+ * check; per-failure-case fixtures derive from it via shallow clone +
+ * mutation in the test files (per the chunk-B1 acceptance: "one fixture
+ * per failure case so the AI doesn't conflate two errors when only one
+ * was triggered").
+ *
+ * Not imported by runtime code (services, the Admin app, the Player
+ * shell). The dev seed (`packages/db/src/seed-dev.ts`) is allowed —
+ * the seed is itself a fixture-loader, and using this shared baseline
+ * keeps the dev-seeded `experience_versions.manifest` blob aligned with
+ * the schema the Inference Gateway (chunk B2) loads at request time.
+ */
+
+import type { Manifest } from './manifest.js';
+import type { WorkflowSideEffect } from './phase.js';
+
+/** Shallow patch for per-test / fixture mutations on a workflow phase. */
+export type PhaseTestPatch = {
+  readonly id?: string;
+  readonly transitions?: ReadonlyArray<{ readonly to: string; readonly when?: string }>;
+  readonly sideEffects?: readonly WorkflowSideEffect[];
+};
+
+/**
+ * Mutate one phase in a cloned manifest. Manifest phases are typed
+ * readonly; tests use this helper instead of unsafe casts.
+ */
+export const patchPhase = (
+  manifest: Manifest,
+  phaseId: string,
+  patch: PhaseTestPatch,
+): void => {
+  const phase = manifest.workflow.phases.find((p) => p.id === phaseId);
+  if (!phase) return;
+  Object.assign(phase as object, patch);
+};
+
+/** Mutate a phase by index (same semantics as `patchPhase`). */
+export const patchPhaseAt = (
+  manifest: Manifest,
+  index: number,
+  patch: PhaseTestPatch,
+): void => {
+  const phase = manifest.workflow.phases[index];
+  if (!phase) return;
+  Object.assign(phase as object, patch);
+};
+
+const TENANT_ID = 'tnt_V1StGXR8_Z5jdHi6B_myT';
+const EXPERIENCE_ID = 'exp_HelloWorldFixture000_';
+const PERSONA_ID = 'per_CrumbHostPersona00_';
+const FIXED_ISO = '2026-01-01T00:00:00.000Z';
+
+/**
+ * A minimal Hello World shape: lobby → guess → resolved, with one
+ * persona binding, one quality tier, one award. Designed so a
+ * single-field mutation can trigger any one of the structural checks
+ * without colliding with another rule.
+ */
+export const validManifestFixture: Manifest = {
+  id: EXPERIENCE_ID,
+  version: '1.0.0',
+  name: 'Hello World',
+  description: 'The smallest manifest the validator accepts.',
+  tenant: TENANT_ID,
+  creator: 'wibly-platform',
+  createdAt: FIXED_ISO,
+  personaBindings: [
+    { role: 'host', personaId: PERSONA_ID },
+  ],
+  inferenceEnvelope: {
+    maxLlmCallsPerSession: 20,
+    maxTokensInPerCall: 2048,
+    maxTokensOutPerCall: 1024,
+    maxTtsSecondsPerSession: 120,
+    qualityTiers: ['fast', 'standard', 'premium', 'creative'],
+  },
+  stateSchema: {
+    session: { type: 'object', properties: { round: { type: 'number' } } },
+    host: { type: 'object', properties: {} },
+    playerPublic: { type: 'object', properties: { score: { type: 'number' } } },
+    playerPrivate: { type: 'object', properties: {} },
+    team: { type: 'object', properties: {} },
+  },
+  workflow: {
+    initialPhase: 'lobby',
+    phases: [
+      {
+        id: 'lobby',
+        inputSet: { actors: ['host'], inputType: 'start' },
+        collectionRule: { kind: 'manual' },
+        transitions: [{ to: 'guess' }],
+        sideEffects: [],
+      },
+      {
+        id: 'guess',
+        inputSet: { actors: ['player'], inputType: 'guess' },
+        collectionRule: { kind: 'all_respond' },
+        transitions: [{ to: 'resolved' }],
+        sideEffects: [],
+      },
+      {
+        id: 'resolved',
+        inputSet: { actors: ['host'], inputType: 'next' },
+        collectionRule: { kind: 'manual' },
+        transitions: [{ to: 'lobby', when: 'play_again' }],
+        sideEffects: [],
+      },
+    ],
+  },
+  concurrentOpportunities: [
+    {
+      id: 'side_chat',
+      attachedToPhases: ['guess'],
+      inputSet: { actors: ['player'], inputType: 'chatter' },
+      collectionRule: { kind: 'timeout', ms: 30_000 },
+      scoringEffect: { kind: 'noop' },
+    },
+  ],
+  scoring: {
+    dimensions: [
+      { id: 'accuracy', label: 'Accuracy', weight: 1, scaleMin: 0, scaleMax: 10 },
+    ],
+    aggregators: [{ kind: 'sum' }],
+    awards: [
+      {
+        id: 'top_guesser',
+        label: 'Top Guesser',
+        dimensionId: 'accuracy',
+        criterion: { kind: 'top_n', n: 1 },
+      },
+    ],
+  },
+  lifecyclePolicies: [
+    {
+      situation: 'player_disconnect',
+      action: {
+        kind: 'pause_session',
+        timeoutMs: 30_000,
+        fallback: 'continue_without_them',
+      },
+    },
+  ],
+  promptSlots: {
+    experienceSystem: 'You are running Hello World, a tiny test Experience.',
+    callTypes: {
+      host_open_phase: 'Open the next phase with one short sentence.',
+      host_recap: {
+        template: 'Recap the round for {playerCount} players.',
+        vars: ['playerCount'],
+      },
+    },
+  },
+  fallbackResponses: {
+    host_open_phase: 'Welcome — let us begin.',
+    host_recap: 'Thanks for playing.',
+  },
+  widgetDependencies: ['Lobby', 'GuessInput', 'Leaderboard'],
+  contentRating: {
+    tier: 'none',
+    audiences: ['consumer'],
+  },
+  portalMetadata: {
+    heroImageUrl: 'https://assets.wibly.example/fixtures/hello-world-hero.png',
+    gameplayImages: [],
+    sampleRoundDescription:
+      'A demonstration round where players guess a number and the host reveals the answer.',
+    occasionTags: ['party', 'quick_game'],
+    minPlayers: 3,
+    maxPlayers: 8,
+    estimatedDurationMinutes: 30,
+  },
+};
+
+/**
+ * Deep clone of the fixture so per-test mutations don't bleed into
+ * other tests. `structuredClone` is in the Node 20 std lib (no polyfill
+ * needed) and handles the JSON-shaped state-schema slices correctly.
+ *
+ * Note: the cloned fixture's `workflow.phases[*].sideEffects` is
+ * `undefined` because `validManifestFixture` does not set the field
+ * — the `PhaseSchema.default([])` on `sideEffects` fills it in when
+ * the fixture is parsed via `ManifestSchema` / `validateManifest`. If
+ * a caller needs the parsed (post-default) shape, run the clone
+ * through `validateManifest` first.
+ */
+export const cloneFixture = (): Manifest =>
+  structuredClone(validManifestFixture);
+
+/**
+ * Chunk B8c — fixture variant that exercises the per-phase
+ * `sideEffects` declaration. Adds:
+ *   - an `inference` side effect on `guess` that writes the structured
+ *     output into `/session/inference/host_judge`,
+ *   - a `scoring` side effect on `resolved` that credits a fixed +1 to
+ *     the active player on the `accuracy` dimension,
+ *
+ * The integration tests under `services/runtime/src/__integration__/`
+ * consume this fixture; the unit tests stick with the bare
+ * `validManifestFixture` so the `sideEffects: []` default path stays
+ * exercised.
+ */
+export const cloneFixtureWithInferenceSideEffect = (): Manifest => {
+  const fixture = cloneFixture();
+  patchPhase(fixture, 'guess', {
+    sideEffects: [
+      {
+        kind: 'inference',
+        callKind: 'host_judge',
+        qualityTier: 'standard',
+        targetPath: '/session/inference/host_judge',
+      },
+    ],
+  });
+  patchPhase(fixture, 'resolved', {
+    sideEffects: [
+      {
+        kind: 'scoring',
+        dimension: 'accuracy',
+        value: 1,
+        source: 'compute',
+      },
+    ],
+  });
+  return fixture;
+};

package/src/index.ts

@@ -0,0 +1,126 @@
+/**
+ * `@platform/manifest` — Experience-manifest schemas and validator.
+ *
+ * Per Vibecode Dev Plan §2.5 the manifest blob lives in a `JSONB`
+ * column on `experience_versions`; this package owns the Zod schema
+ * that gates writes to that column and the `validateManifest` function
+ * that runs on every read / publish boundary. Per the chunk-B1 trap,
+ * `validateManifest` is the *only* validation entrypoint downstream
+ * services should reach for — ad-hoc Zod parses or shape checks
+ * elsewhere are a regression.
+ *
+ * Built in chunk B1; see `docs/chunks/B1.md` for the close note.
+ */
+
+export {
+  ActorKindSchema,
+  CollectionRuleSchema,
+  InferenceSideEffectSchema,
+  InputSetSchema,
+  PersonaMemorySideEffectSchema,
+  PhaseSchema,
+  ScoringSideEffectSchema,
+  StateWriteSideEffectSchema,
+  TransitionSchema,
+  WorkflowSideEffectSchema,
+  type ActorKind,
+  type CollectionRule,
+  type InputSet,
+  type ManifestPhase,
+  type Phase,
+  type Transition,
+  type WorkflowSideEffect,
+} from './phase.js';
+
+export {
+  isSmutTierCapable,
+  portalContentRatingLabel,
+  safetyFloorFromContentRatingTier,
+} from './content-rating.js';
+
+export {
+  DEFAULT_ESTIMATED_DURATION_MINUTES,
+  DEFAULT_MAX_PLAYERS,
+  DEFAULT_MIN_PLAYERS,
+  portalContentCategoryLabel,
+  portalDurationLabel,
+  portalPlayersLabel,
+} from './portal-display.js';
+
+export {
+  AwardCriterionSchema,
+  AwardDefinitionSchema,
+  BundleContextSlotsSchema,
+  CallKindSchema,
+  ConcurrentOpportunitySchema,
+  ContentRatingAudienceSchema,
+  ContentRatingFloorSchema,
+  ContentRatingSchema,
+  ExperienceContentRatingTierSchema,
+  FallbackResponsesSchema,
+  GameplayImageSchema,
+  GameplayVideoSchema,
+  InferenceEnvelopeSchema,
+  LifecycleActionSchema,
+  LifecyclePolicySchema,
+  LifecycleSituationSchema,
+  ManifestIdSchema,
+  ManifestSchema,
+  ManifestTenantIdSchema,
+  OccasionTagSchema,
+  PersonaBindingSchema,
+  PersonaIdSchema,
+  PortalMetadataSchema,
+  PromptSlotsSchema,
+  PromptSlotValueSchema,
+  QualityTierSchema,
+  ScoringAggregatorSchema,
+  ScoringDimensionSchema,
+  ScoringSchema,
+  StateSchemaSchema,
+  WorkflowSchema,
+  type AwardCriterion,
+  type AwardDefinition,
+  type BundleContextSlots,
+  type CallKind,
+  type ConcurrentOpportunity,
+  type ContentRating,
+  type ContentRatingAudience,
+  type ContentRatingFloor,
+  type ExperienceContentRatingTier,
+  type FallbackResponses,
+  type GameplayImage,
+  type GameplayVideo,
+  type InferenceEnvelope,
+  type JsonValue,
+  type LifecycleAction,
+  type LifecyclePolicy,
+  type LifecycleSituation,
+  type Manifest,
+  type ManifestId,
+  type ManifestTenantId,
+  type OccasionTag,
+  type PersonaBinding,
+  type PersonaId,
+  type PortalMetadata,
+  type PromptSlots,
+  type PromptSlotValue,
+  type QualityTier,
+  type Scoring,
+  type ScoringAggregator,
+  type ScoringDimension,
+  type StateSchema,
+  type Workflow,
+} from './manifest.js';
+
+export {
+  validateManifest,
+  type ValidationError,
+  type ValidationErrorCode,
+} from './validate.js';
+
+export {
+  cloneFixture,
+  cloneFixtureWithInferenceSideEffect,
+  validManifestFixture,
+} from './fixtures.js';