@wibly/internal-manifest 0.1.1

package/src/phase.test.ts

@@ -0,0 +1,227 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  ActorKindSchema,
+  CollectionRuleSchema,
+  InputSetSchema,
+  PhaseSchema,
+  TransitionSchema,
+  WorkflowSideEffectSchema,
+} from './phase.js';
+
+describe('ActorKindSchema', () => {
+  it.each(['host', 'player', 'team'])('accepts %s', (kind) => {
+    expect(ActorKindSchema.safeParse(kind).success).toBe(true);
+  });
+
+  it('rejects an unknown actor', () => {
+    expect(ActorKindSchema.safeParse('observer').success).toBe(false);
+  });
+});
+
+describe('InputSetSchema', () => {
+  it('accepts a well-formed input set', () => {
+    expect(
+      InputSetSchema.safeParse({
+        actors: ['player'],
+        inputType: 'guess',
+      }).success,
+    ).toBe(true);
+  });
+
+  it('rejects an empty actors array (a phase nobody answers is undriveable)', () => {
+    const result = InputSetSchema.safeParse({
+      actors: [],
+      inputType: 'guess',
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects an empty inputType', () => {
+    expect(
+      InputSetSchema.safeParse({ actors: ['player'], inputType: '' }).success,
+    ).toBe(false);
+  });
+});
+
+describe('CollectionRuleSchema', () => {
+  it('accepts every variant', () => {
+    expect(CollectionRuleSchema.safeParse({ kind: 'all_respond' }).success).toBe(
+      true,
+    );
+    expect(
+      CollectionRuleSchema.safeParse({ kind: 'first_respond', count: 3 })
+        .success,
+    ).toBe(true);
+    expect(
+      CollectionRuleSchema.safeParse({ kind: 'timeout', ms: 30_000 }).success,
+    ).toBe(true);
+    expect(CollectionRuleSchema.safeParse({ kind: 'manual' }).success).toBe(
+      true,
+    );
+  });
+
+  it('rejects a zero-ms timeout (would deadlock the Runtime)', () => {
+    expect(
+      CollectionRuleSchema.safeParse({ kind: 'timeout', ms: 0 }).success,
+    ).toBe(false);
+  });
+
+  it('rejects a zero-count first_respond (would resolve before any response)', () => {
+    expect(
+      CollectionRuleSchema.safeParse({ kind: 'first_respond', count: 0 })
+        .success,
+    ).toBe(false);
+  });
+
+  it('rejects an unknown kind', () => {
+    expect(
+      CollectionRuleSchema.safeParse({ kind: 'eventually' }).success,
+    ).toBe(false);
+  });
+});
+
+describe('TransitionSchema', () => {
+  it('accepts a transition without a `when` guard', () => {
+    expect(TransitionSchema.safeParse({ to: 'guess' }).success).toBe(true);
+  });
+
+  it('accepts a transition with a `when` guard', () => {
+    expect(
+      TransitionSchema.safeParse({ to: 'guess', when: 'has_quorum' }).success,
+    ).toBe(true);
+  });
+
+  it('rejects an empty `to`', () => {
+    expect(TransitionSchema.safeParse({ to: '' }).success).toBe(false);
+  });
+});
+
+describe('PhaseSchema', () => {
+  const baseline = {
+    id: 'lobby',
+    inputSet: { actors: ['host'], inputType: 'start' },
+    collectionRule: { kind: 'manual' },
+    transitions: [{ to: 'guess' }],
+  };
+
+  it('accepts a well-formed phase', () => {
+    expect(PhaseSchema.safeParse(baseline).success).toBe(true);
+  });
+
+  it('rejects a phase with no transitions (terminal phases require an explicit exit edge in MVP)', () => {
+    const result = PhaseSchema.safeParse({ ...baseline, transitions: [] });
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(
+        result.error.issues.some((i) => i.path.includes('transitions')),
+      ).toBe(true);
+    }
+  });
+
+  it('rejects an empty phase id', () => {
+    const result = PhaseSchema.safeParse({ ...baseline, id: '' });
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects a phase missing the input set', () => {
+    const incomplete: Record<string, unknown> = { ...baseline };
+    delete incomplete.inputSet;
+    expect(PhaseSchema.safeParse(incomplete).success).toBe(false);
+  });
+
+  it('defaults sideEffects to an empty array (chunk B8c)', () => {
+    const result = PhaseSchema.safeParse(baseline);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.sideEffects).toEqual([]);
+    }
+  });
+
+  it('accepts a phase that declares sideEffects (chunk B8c)', () => {
+    const result = PhaseSchema.safeParse({
+      ...baseline,
+      sideEffects: [
+        { kind: 'state_write', patches: [{ op: 'replace', path: '/x', value: 1 }] },
+        { kind: 'inference', callKind: 'host_judge' },
+      ],
+    });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.sideEffects).toHaveLength(2);
+    }
+  });
+
+  it('rejects an unknown side-effect kind', () => {
+    const result = PhaseSchema.safeParse({
+      ...baseline,
+      sideEffects: [{ kind: 'unknown', value: 1 }],
+    });
+    expect(result.success).toBe(false);
+  });
+});
+
+describe('WorkflowSideEffectSchema (chunk B8c)', () => {
+  it('accepts the state_write variant', () => {
+    const result = WorkflowSideEffectSchema.safeParse({
+      kind: 'state_write',
+      patches: [{ op: 'replace', path: '/session/round', value: 1 }],
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it('rejects a state_write with zero patches (no-op should be omitted)', () => {
+    const result = WorkflowSideEffectSchema.safeParse({
+      kind: 'state_write',
+      patches: [],
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it('accepts an inference effect with a targetPath JSON-Pointer', () => {
+    const result = WorkflowSideEffectSchema.safeParse({
+      kind: 'inference',
+      callKind: 'host_judge',
+      qualityTier: 'standard',
+      targetPath: '/session/inference/host_judge',
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it('rejects an inference effect whose callKind is outside the enum', () => {
+    const result = WorkflowSideEffectSchema.safeParse({
+      kind: 'inference',
+      callKind: 'totally_made_up',
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects an inference effect with a malformed targetPath', () => {
+    const result = WorkflowSideEffectSchema.safeParse({
+      kind: 'inference',
+      callKind: 'host_judge',
+      targetPath: 'not-a-pointer',
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it('accepts a persona_memory effect', () => {
+    const result = WorkflowSideEffectSchema.safeParse({
+      kind: 'persona_memory',
+      personaId: 'per_abc123',
+      op: 'write',
+      payload: { note: 'hello' },
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it('accepts a scoring effect with a negative value (corrections)', () => {
+    const result = WorkflowSideEffectSchema.safeParse({
+      kind: 'scoring',
+      dimension: 'accuracy',
+      value: -1,
+      source: 'submit',
+    });
+    expect(result.success).toBe(true);
+  });
+});

package/src/phase.ts

@@ -0,0 +1,304 @@
+/**
+ * Manifest-time Zod schemas for the workflow primitives.
+ *
+ * Per Platform Spec §3.9.1: every Experience is a state machine of `Phase`s.
+ * Each phase declares an `InputSet` (whose inputs are accepted) and a
+ * `CollectionRule` (when the phase ends), plus zero or more `Transition`s
+ * out.
+ *
+ * The narrow on-the-wire types live in `@platform/protocol`; this package
+ * wraps them in Zod so a manifest blob (parsed from JSONB or hand-authored
+ * by a Creator) can be validated with one call. The protocol types stay
+ * minimal and TS-only because every WebSocket frame pays for those types
+ * at runtime — the Zod machinery has no business there.
+ *
+ * Per Vibecode Dev Plan §4.6 the protocol package is the *single* source
+ * of truth for the on-the-wire shape; the manifest layer is a strict
+ * superset (the chunk-B8c `sideEffects` declaration lives on the
+ * manifest's `Phase` but does NOT travel the protocol — phases on the
+ * wire are still the bare protocol shape).
+ *
+ * Per chunk-A1 §4.1: `z.infer<typeof X>` returns the schema's *output*
+ * type. The manifest-layer `Phase` re-export here is the schema-inferred
+ * shape (with `sideEffects: WorkflowSideEffect[]`); the wire-format
+ * `Phase` stays in `@platform/protocol` and is re-imported there.
+ */
+
+import type {
+  ActorKind,
+  CollectionRule,
+  InputSet,
+  Phase,
+  Transition,
+} from '@wibly/internal-protocol';
+import { z } from 'zod';
+
+// -----------------------------------------------------------------------------
+// Actor / input set
+// -----------------------------------------------------------------------------
+
+export const ActorKindSchema = z.enum(['host', 'player', 'team']);
+
+/**
+ * The set of actors whose input the Runtime accepts during this phase,
+ * plus the manifest-defined `inputType` tag (e.g. `'guess'`, `'vote'`,
+ * `'free_text'`). The Runtime resolves the per-input Zod schema via the
+ * manifest's `stateSchema` / handler hook; the protocol carries
+ * `inputType` as an opaque string.
+ *
+ * `actors` is non-empty because a phase that accepts input from no one
+ * has no path forward; the validator catches that case at manifest time
+ * rather than at runtime.
+ */
+export const InputSetSchema = z.object({
+  actors: z.array(ActorKindSchema).min(1),
+  inputType: z.string().min(1),
+});
+
+// -----------------------------------------------------------------------------
+// Collection rule
+// -----------------------------------------------------------------------------
+
+/**
+ * When the phase ends. Discriminated on `kind` so the Runtime can branch
+ * exhaustively. New variants land with the chunk that needs them; per
+ * the chunk-B0 trap, keep the protocol shape narrow.
+ *
+ * `manual` collection rules require a host trigger (e.g. a `host_judge`
+ * call resolves the phase). `timeout.ms` is positive — a zero-timeout
+ * phase is a Runtime infinite-loop hazard the validator should catch.
+ */
+export const CollectionRuleSchema = z.discriminatedUnion('kind', [
+  z.object({ kind: z.literal('all_respond') }),
+  z.object({
+    kind: z.literal('first_respond'),
+    count: z.number().int().positive(),
+  }),
+  z.object({ kind: z.literal('timeout'), ms: z.number().int().positive() }),
+  z.object({ kind: z.literal('manual') }),
+]);
+
+// -----------------------------------------------------------------------------
+// Transition + phase
+// -----------------------------------------------------------------------------
+
+/**
+ * One outgoing edge from a phase. The Runtime evaluates transitions in
+ * declaration order on collection-rule fire; the first matching
+ * transition is taken. Conditions live behind manifest-defined `when`
+ * tags; the protocol carries the tag as an opaque string.
+ */
+export const TransitionSchema = z.object({
+  to: z.string().min(1),
+  when: z.string().min(1).optional(),
+});
+
+// -----------------------------------------------------------------------------
+// Phase side-effect declarations (chunk B8c)
+// -----------------------------------------------------------------------------
+
+/**
+ * Quality-tier enum lifted here (chunk B8c) so the side-effect schema
+ * can carry an optional `qualityTier` without requiring a circular
+ * import. Mirrors `QualityTierSchema` re-exported from `manifest.ts`.
+ */
+const PhaseSideEffectQualityTierSchema = z.enum([
+  'fast',
+  'standard',
+  'premium',
+  'creative',
+]);
+
+/**
+ * Known `callKind` set lifted here for the same reason as
+ * {@link PhaseSideEffectQualityTierSchema}. Kept exactly in lock-step
+ * with `CallKindSchema` in `manifest.ts`; `manifest.ts` imports this
+ * symbol so they cannot drift.
+ */
+export const CallKindSchema = z.enum([
+  'host_open_phase',
+  'host_judge',
+  'host_resolve',
+  'host_recap',
+  'judge_funniness',
+  'narrate_event',
+  'classify',
+  'compose_clue',
+]);
+
+/**
+ * RFC 6901 JSON-Pointer validator. Accepts the empty pointer `""`
+ * (root) and any pointer starting with `/`. We do NOT enforce
+ * per-segment escaping at the schema layer — the JSON-Patch library
+ * the Runtime uses already rejects malformed segments at apply time;
+ * doing it twice would surface the same error in two places.
+ */
+const JsonPointerSchema = z
+  .string()
+  .refine((s) => s === '' || s.startsWith('/'), {
+    message: 'must be an RFC 6901 JSON-Pointer (empty or starting with "/")',
+  });
+
+/**
+ * `state_write` side effect — apply a list of JSON-Patch ops to the
+ * session state. The Runtime resolves the patches against the
+ * registry-broadcast diff path; the manifest does not constrain the
+ * shape of `value` because the per-Experience state schema is opaque
+ * to the manifest layer.
+ */
+export const StateWriteSideEffectSchema = z.object({
+  kind: z.literal('state_write'),
+  patches: z
+    .array(
+      z.object({
+        op: z.enum(['add', 'remove', 'replace', 'move', 'copy']),
+        path: JsonPointerSchema,
+        from: JsonPointerSchema.optional(),
+        value: z.unknown().optional(),
+      }),
+    )
+    .min(1),
+});
+
+/**
+ * `inference` side effect — dispatch a Gateway call. `callKind` keys
+ * the prompt-composition layer 4 entry; `slots` carries per-call
+ * variables for template interpolation. `targetPath` is an
+ * RFC 6901 JSON-Pointer the Runtime writes the inference output to
+ * once the Gateway returns (default at handler time:
+ * `/session/inference/<callKind>`).
+ */
+export const InferenceSideEffectSchema = z.object({
+  kind: z.literal('inference'),
+  callKind: CallKindSchema,
+  qualityTier: PhaseSideEffectQualityTierSchema.optional(),
+  slots: z.record(z.unknown()).optional(),
+  targetPath: JsonPointerSchema.optional(),
+});
+
+/**
+ * `persona_memory` side effect — read or write into the bound
+ * persona's memory. Per `services/persona/src/contract.ts` the
+ * effective write mode is decided by the Persona Service against the
+ * tenant + player consent posture; the manifest only declares intent.
+ */
+export const PersonaMemorySideEffectSchema = z.object({
+  kind: z.literal('persona_memory'),
+  personaId: z.string().min(1),
+  op: z.enum(['read', 'write']),
+  payload: z.record(z.unknown()).optional(),
+});
+
+/**
+ * `scoring` side effect — append one row to the scoring ledger
+ * (chunk B8c). `dimension` references a `scoring.dimensions[].id`;
+ * cross-reference checking runs in `validateManifest`. `value` may be
+ * negative when the Runtime is recording a correction; the
+ * append-only ledger never updates the original row.
+ */
+export const ScoringSideEffectSchema = z.object({
+  kind: z.literal('scoring'),
+  dimension: z.string().min(1),
+  actorPlayerId: z.string().min(1).optional(),
+  value: z.number(),
+  source: z.enum(['submit', 'judge', 'compute', 'award']),
+  metadata: z.record(z.unknown()).optional(),
+});
+
+/**
+ * Discriminated union of every side effect a phase can declare. Wired
+ * to the runtime's `WorkflowSideEffect` set in
+ * `services/runtime/src/workflow/side-effects.ts`. The manifest type
+ * is the input contract; the runtime type is the dispatch contract;
+ * they are kept structurally compatible by the workflow's
+ * `resolveSideEffects` handler.
+ */
+export const WorkflowSideEffectSchema = z.discriminatedUnion('kind', [
+  StateWriteSideEffectSchema,
+  InferenceSideEffectSchema,
+  PersonaMemorySideEffectSchema,
+  ScoringSideEffectSchema,
+]);
+
+export type WorkflowSideEffect = z.infer<typeof WorkflowSideEffectSchema>;
+
+/**
+ * One workflow phase. The structural rule "every phase has at least one
+ * outgoing transition" is enforced here at the schema level rather than
+ * deferred to `validateManifest` so a hand-authored phase blob fails at
+ * its own boundary, with a located error, before the cross-phase checks
+ * run.
+ *
+ * `sideEffects` defaults to `[]` so every existing fixture parses
+ * unchanged (B8c widening; see chunk-B8b deferral notes). The Runtime
+ * resolver reads this array via the injected `PhaseSideEffectResolver`
+ * default.
+ *
+ * Chunk B12 extensions:
+ *
+ *   - `subPhases?: Record<string, Phase>` — named sub-phase
+ *     declarations the workflow interpreter looks up when an
+ *     Experience's server-side bundle calls `ctx.runSubPhase(key)`
+ *     (or the host emits `host.runSubPhase` with `{ subPhaseKey }`).
+ *     Keys are manifest-local strings; the value is a recursive
+ *     `Phase` shape (sub-phases can themselves declare sub-phases,
+ *     though MVP doesn't exercise that depth). The chunk-B8b
+ *     interpreter's existing `host.runSubPhase` path took an inline
+ *     Phase object via `payload.data.subPhase`; chunk B12 keeps
+ *     that overload for back-compat and adds the keyed lookup.
+ *   - `computeScoreOnEnter?: boolean` — when `true`, the workflow
+ *     transition fires the sandbox `computeScore` hook after the
+ *     phase swap and before declarative side effects. Default
+ *     `false` keeps every existing fixture parsing unchanged.
+ *   - `endsRound?: boolean` — when `true`, the workflow transition
+ *     fires the sandbox `onRoundEnd` hook on phase EXIT (before
+ *     the swap). Used by multi-round Experiences (Rashomon) to
+ *     trigger end-of-round bookkeeping in the bundle.
+ */
+export const PhaseSchema = z.lazy(() =>
+  z.object({
+    id: z.string().min(1),
+    inputSet: InputSetSchema,
+    collectionRule: CollectionRuleSchema,
+    transitions: z.array(TransitionSchema).min(1),
+    sideEffects: z.array(WorkflowSideEffectSchema).default([]),
+    subPhases: z.record(z.string().min(1), PhaseSchema).optional(),
+    computeScoreOnEnter: z.boolean().optional(),
+    endsRound: z.boolean().optional(),
+  }),
+) as z.ZodType<ManifestPhase>;
+
+// -----------------------------------------------------------------------------
+// Re-exports
+// -----------------------------------------------------------------------------
+
+export type { ActorKind, CollectionRule, InputSet, Phase, Transition };
+
+/**
+ * Manifest-layer `Phase` shape with `sideEffects` attached (chunk B8c)
+ * + the B12 fields (`subPhases`, `computeScoreOnEnter`, `endsRound`).
+ * Use this in places that read the extended declaration — the
+ * Runtime's workflow side-effect resolver, the sub-phase lookup
+ * helper, and the manifest validator. Most consumers can keep
+ * importing `Phase` (the on-wire shape) and stay agnostic of the
+ * extension.
+ *
+ * Structurally a superset of the protocol's `Phase`; the
+ * `sideEffects` field defaults to `[]` at parse time so existing
+ * fixtures parse unchanged, and the B12 extensions are optional.
+ *
+ * Declared as a TS type (not `z.infer<typeof PhaseSchema>`) because
+ * the schema itself is recursive (`subPhases` references
+ * `PhaseSchema`) — Zod can't infer the recursive type, so we
+ * declare the shape here and reference it from the lazy schema.
+ */
+export type ManifestPhase = {
+  readonly id: string;
+  readonly inputSet: InputSet;
+  readonly collectionRule: CollectionRule;
+  readonly transitions: readonly Transition[];
+  readonly sideEffects: readonly WorkflowSideEffect[];
+  readonly subPhases?: Readonly<Record<string, ManifestPhase>>;
+  readonly computeScoreOnEnter?: boolean;
+  readonly endsRound?: boolean;
+};

package/src/portal-display.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'vitest';
+
+import { PortalMetadataSchema } from './manifest.js';
+import {
+  portalContentCategoryLabel,
+  portalDurationLabel,
+  portalPlayersLabel,
+} from './portal-display.js';
+
+describe('portal display helpers', () => {
+  it('formats player counts as a range', () => {
+    expect(portalPlayersLabel({ minPlayers: 3, maxPlayers: 8 })).toBe(
+      '3 - 8 players',
+    );
+    expect(portalPlayersLabel({ minPlayers: 4, maxPlayers: 4 })).toBe(
+      '4 players',
+    );
+  });
+
+  it('formats duration labels', () => {
+    expect(portalDurationLabel(45)).toBe('~45 min');
+    expect(portalDurationLabel(60)).toBe('~1 hr');
+    expect(portalDurationLabel(90)).toBe('~1 hr 30 min');
+  });
+
+  it('hides the all-ages content category pill', () => {
+    expect(portalContentCategoryLabel('none')).toBeNull();
+    expect(portalContentCategoryLabel('pg13')).toBe('PG-13');
+  });
+});
+
+describe('PortalMetadataSchema player defaults', () => {
+  it('applies defaults for legacy manifests', () => {
+    const parsed = PortalMetadataSchema.parse({
+      heroImageUrl: 'https://assets.wibly.example/hero.png',
+      sampleRoundDescription: 'Sample round copy.',
+      occasionTags: ['party'],
+    });
+    expect(parsed.minPlayers).toBe(3);
+    expect(parsed.maxPlayers).toBe(8);
+    expect(parsed.estimatedDurationMinutes).toBe(30);
+  });
+
+  it('rejects maxPlayers below minPlayers', () => {
+    const result = PortalMetadataSchema.safeParse({
+      heroImageUrl: 'https://assets.wibly.example/hero.png',
+      sampleRoundDescription: 'Sample round copy.',
+      occasionTags: ['party'],
+      minPlayers: 6,
+      maxPlayers: 4,
+    });
+    expect(result.success).toBe(false);
+  });
+});

package/src/portal-display.ts

@@ -0,0 +1,40 @@
+import { portalContentRatingLabel } from './content-rating.js';
+import type {
+  ExperienceContentRatingTier,
+  PortalMetadata,
+} from './manifest.js';
+
+export const DEFAULT_MIN_PLAYERS = 3;
+export const DEFAULT_MAX_PLAYERS = 8;
+export const DEFAULT_ESTIMATED_DURATION_MINUTES = 30;
+
+export const portalPlayersLabel = (
+  metadata: Pick<PortalMetadata, 'minPlayers' | 'maxPlayers'>,
+): string => {
+  if (metadata.minPlayers === metadata.maxPlayers) {
+    return `${metadata.minPlayers} player${metadata.minPlayers === 1 ? '' : 's'}`;
+  }
+  return `${metadata.minPlayers} - ${metadata.maxPlayers} players`;
+};
+
+export const portalDurationLabel = (minutes: number): string => {
+  if (minutes < 60) {
+    return `~${minutes} min`;
+  }
+  const hours = Math.floor(minutes / 60);
+  const remainder = minutes % 60;
+  if (remainder === 0) {
+    return `~${hours} hr`;
+  }
+  return `~${hours} hr ${remainder} min`;
+};
+
+/** Returns a catalogue category pill label, or null when none should show. */
+export const portalContentCategoryLabel = (
+  tier: ExperienceContentRatingTier,
+): string | null => {
+  if (tier === 'none') {
+    return null;
+  }
+  return portalContentRatingLabel(tier);
+};