@wibly/internal-manifest 0.1.1

package/src/validate.test.ts

@@ -0,0 +1,310 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  cloneFixture,
+  patchPhase,
+  patchPhaseAt,
+  validManifestFixture,
+} from './fixtures.js';
+import { validateManifest, type ValidationErrorCode } from './validate.js';
+
+const expectErrorCode = (
+  errors: ReadonlyArray<{ readonly code: ValidationErrorCode }>,
+  code: ValidationErrorCode,
+): void => {
+  expect(errors.map((e) => e.code)).toContain(code);
+};
+
+describe('validateManifest — happy path', () => {
+  it('returns Ok on the baseline fixture', () => {
+    const result = validateManifest(validManifestFixture);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      // The Ok branch surfaces the parsed manifest, not the input;
+      // round-trip equality is the contract.
+      expect(result.value.id).toBe(validManifestFixture.id);
+      expect(result.value.workflow.phases).toHaveLength(
+        validManifestFixture.workflow.phases.length,
+      );
+    }
+  });
+
+  it('returns Ok when `tenant` is null (first-party)', () => {
+    const fixture = cloneFixture();
+    fixture.tenant = null;
+    expect(validateManifest(fixture).ok).toBe(true);
+  });
+
+  it('returns Ok when bundle reservation fields are omitted (Chunk B18)', () => {
+    const fixture = cloneFixture();
+    delete (fixture as { bundleCompatible?: unknown }).bundleCompatible;
+    delete (fixture as { bundleScopedDimensions?: unknown })
+      .bundleScopedDimensions;
+    delete (fixture as { bundleWriteDimensions?: unknown })
+      .bundleWriteDimensions;
+    delete (fixture as { bundleContextSlots?: unknown }).bundleContextSlots;
+    expect(validateManifest(fixture).ok).toBe(true);
+  });
+
+  it('returns Ok when bundle reservation fields are populated (Chunk B18)', () => {
+    const fixture = cloneFixture();
+    fixture.bundleCompatible = true;
+    fixture.bundleScopedDimensions = ['score'];
+    fixture.bundleWriteDimensions = ['notes'];
+    fixture.bundleContextSlots = { theme: 'party' };
+    const result = validateManifest(fixture);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.bundleCompatible).toBe(true);
+      expect(result.value.bundleScopedDimensions).toEqual(['score']);
+    }
+  });
+});
+
+describe('validateManifest — schema-level failures surface as `schema` errors', () => {
+  it('reports a schema error when a top-level field is missing', () => {
+    const fixture: Record<string, unknown> = cloneFixture();
+    delete fixture.name;
+    const result = validateManifest(fixture);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expectErrorCode(result.error, 'schema');
+      expect(result.error.some((e) => e.path.includes('name'))).toBe(true);
+    }
+  });
+
+  it('skips structural checks when the parse fails', () => {
+    // Deliberately combine a schema error AND a structural error;
+    // verify only the schema error is surfaced (structural traversal
+    // requires a parsed shape).
+    const fixture = cloneFixture() as { name?: unknown; workflow: { initialPhase: string } };
+    delete fixture.name;
+    fixture.workflow.initialPhase = 'nonexistent';
+    const result = validateManifest(fixture);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.every((e) => e.code === 'schema')).toBe(true);
+    }
+  });
+});
+
+describe('validateManifest — structural: initial phase', () => {
+  it('rejects a manifest whose initialPhase is not declared in phases', () => {
+    const fixture = cloneFixture();
+    fixture.workflow.initialPhase = 'nonexistent';
+    const result = validateManifest(fixture);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expectErrorCode(result.error, 'unknown_initial_phase');
+      const issue = result.error.find(
+        (e) => e.code === 'unknown_initial_phase',
+      );
+      expect(issue?.path).toEqual(['workflow', 'initialPhase']);
+    }
+  });
+});
+
+describe('validateManifest — structural: duplicate phase ids', () => {
+  it('rejects a manifest where two phases share an id', () => {
+    const fixture = cloneFixture();
+    // Make `lobby` and `guess` share an id; mutate `guess` only so
+    // every other check still has a coherent traversal target.
+    patchPhaseAt(fixture, 1, { id: 'lobby' });
+    const result = validateManifest(fixture);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expectErrorCode(result.error, 'duplicate_phase_id');
+    }
+  });
+});
+
+describe('validateManifest — structural: transition target', () => {
+  it('rejects a manifest whose transition points to a non-existent phase', () => {
+    const fixture = cloneFixture();
+    patchPhaseAt(fixture, 0, { transitions: [{ to: 'nonexistent' }] });
+    const result = validateManifest(fixture);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expectErrorCode(result.error, 'unknown_transition_target');
+      const issue = result.error.find(
+        (e) => e.code === 'unknown_transition_target',
+      );
+      expect(issue?.path).toEqual([
+        'workflow',
+        'phases',
+        0,
+        'transitions',
+        0,
+        'to',
+      ]);
+    }
+  });
+});
+
+describe('validateManifest — structural: unreachable phases', () => {
+  it('rejects a manifest with a phase no transition points to', () => {
+    // Build a manifest where `guess` is reachable but `resolved` is
+    // not — the lobby transition jumps straight back to itself, and
+    // guess transitions back to lobby. Hello-World fixture's
+    // resolved-phase loops back to lobby; we have to break that.
+    const fixture = cloneFixture();
+    // lobby → guess, guess → lobby, resolved still has its old
+    // outgoing edge but nothing points TO it.
+    patchPhaseAt(fixture, 1, { transitions: [{ to: 'lobby' }] });
+    const result = validateManifest(fixture);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expectErrorCode(result.error, 'unreachable_phase');
+      const issue = result.error.find((e) => e.code === 'unreachable_phase');
+      expect(issue?.message).toContain('resolved');
+    }
+  });
+
+  it('does not flag any phase as unreachable when the workflow is a single self-loop', () => {
+    const fixture = cloneFixture();
+    fixture.workflow.initialPhase = 'lobby';
+    fixture.workflow.phases = [
+      {
+        id: 'lobby',
+        inputSet: { actors: ['host'], inputType: 'tick' },
+        collectionRule: { kind: 'manual' },
+        transitions: [{ to: 'lobby' }],
+        sideEffects: [],
+      },
+    ];
+    fixture.concurrentOpportunities = [];
+    const result = validateManifest(fixture);
+    expect(result.ok).toBe(true);
+  });
+});
+
+describe('validateManifest — structural: persona-binding role uniqueness', () => {
+  it('rejects two bindings sharing a role', () => {
+    const fixture = cloneFixture();
+    fixture.personaBindings = [
+      { role: 'host', personaId: 'per_first0000000000000' },
+      { role: 'host', personaId: 'per_second000000000000' },
+    ];
+    const result = validateManifest(fixture);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expectErrorCode(result.error, 'duplicate_persona_role');
+    }
+  });
+});
+
+describe('validateManifest — structural: opportunity phase references', () => {
+  it('rejects an opportunity attached to a non-existent phase', () => {
+    const fixture = cloneFixture();
+    fixture.concurrentOpportunities = [
+      {
+        id: 'side_chat',
+        attachedToPhases: ['nowhere'],
+        inputSet: { actors: ['player'], inputType: 'chatter' },
+        collectionRule: { kind: 'timeout', ms: 30_000 },
+        scoringEffect: { kind: 'noop' },
+      },
+    ];
+    const result = validateManifest(fixture);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expectErrorCode(result.error, 'unknown_opportunity_phase');
+    }
+  });
+});
+
+describe('validateManifest — structural: award dimension references', () => {
+  it('rejects an award referencing a missing scoring dimension', () => {
+    const fixture = cloneFixture();
+    fixture.scoring.awards = [
+      {
+        id: 'top_guesser',
+        label: 'Top Guesser',
+        dimensionId: 'speed',
+        criterion: { kind: 'top_n', n: 1 },
+      },
+    ];
+    const result = validateManifest(fixture);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expectErrorCode(result.error, 'unknown_award_dimension');
+    }
+  });
+});
+
+describe('validateManifest — structural: phase side effects (chunk B8c)', () => {
+  it('rejects a scoring side effect referencing an unknown dimension', () => {
+    const fixture = cloneFixture();
+    patchPhase(fixture, 'guess', {
+      sideEffects: [
+        {
+          kind: 'scoring',
+          dimension: 'speed',
+          value: 1,
+          source: 'submit',
+        },
+      ],
+    });
+    const result = validateManifest(fixture);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expectErrorCode(result.error, 'unknown_side_effect_scoring_dimension');
+    }
+  });
+
+  it('rejects a persona_memory side effect referencing an unbound persona', () => {
+    const fixture = cloneFixture();
+    patchPhase(fixture, 'guess', {
+      sideEffects: [
+        {
+          kind: 'persona_memory',
+          personaId: 'per_unbound00000000000',
+          op: 'write',
+        },
+      ],
+    });
+    const result = validateManifest(fixture);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expectErrorCode(result.error, 'unknown_side_effect_persona_binding');
+    }
+  });
+
+  it('accepts a phase with valid scoring + inference side effects', () => {
+    const fixture = cloneFixture();
+    patchPhase(fixture, 'guess', {
+      sideEffects: [
+        {
+          kind: 'scoring',
+          dimension: 'accuracy',
+          value: 1,
+          source: 'submit',
+        },
+        {
+          kind: 'inference',
+          callKind: 'host_judge',
+          targetPath: '/session/inference/host_judge',
+        },
+      ],
+    });
+    const result = validateManifest(fixture);
+    expect(result.ok).toBe(true);
+  });
+});
+
+describe('validateManifest — multiple structural failures surface together', () => {
+  it('reports both a duplicate-role and an unknown-initial-phase error in one call', () => {
+    const fixture = cloneFixture();
+    fixture.personaBindings = [
+      { role: 'host', personaId: 'per_first0000000000000' },
+      { role: 'host', personaId: 'per_second000000000000' },
+    ];
+    fixture.workflow.initialPhase = 'nonexistent';
+    const result = validateManifest(fixture);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expectErrorCode(result.error, 'duplicate_persona_role');
+      expectErrorCode(result.error, 'unknown_initial_phase');
+    }
+  });
+});

package/src/validate.ts

@@ -0,0 +1,385 @@
+/**
+ * Manifest validation — schema parse + structural cross-field checks.
+ *
+ * Per the chunk-B1 spec: `validateManifest` runs the full Zod schema
+ * check, then layers structural validations the schema cannot express
+ * (cross-field references between phases / transitions, persona-binding
+ * uniqueness, scoring-award dimension references, reachability of every
+ * phase from `initialPhase`).
+ *
+ * Returns `Result<Manifest, readonly ValidationError[]>` so the caller
+ * branches once on the discriminant. Per the chunk-B1 trap: this is the
+ * *only* manifest-validation entrypoint; downstream consumers must not
+ * reach into `ManifestSchema.safeParse` directly. New checks land here,
+ * not in ad-hoc utilities sprinkled across services.
+ *
+ * The structural checks short-circuit only on errors that would make
+ * later checks meaningless (e.g. duplicate phase ids would mis-key the
+ * reachability traversal). The Zod parse always runs first; if the
+ * parse fails the structural checks are skipped because the manifest
+ * doesn't have a valid shape to traverse.
+ */
+
+import { err, ok, type Result } from '@wibly/internal-shared';
+import type { ZodIssue } from 'zod';
+
+import {
+  ManifestSchema,
+  type AwardDefinition,
+  type ConcurrentOpportunity,
+  type Manifest,
+  type PersonaBinding,
+  type Workflow,
+} from './manifest.js';
+import type { ManifestPhase } from './phase.js';
+
+// -----------------------------------------------------------------------------
+// ValidationError — categorised, located, operator-readable
+// -----------------------------------------------------------------------------
+
+/**
+ * Categorised manifest-validation failure.
+ *
+ * - `schema`                       — Zod-level shape failure. `path` /
+ *                                    `message` come from a `ZodIssue`.
+ * - `unknown_initial_phase`        — `workflow.initialPhase` doesn't
+ *                                    appear in `workflow.phases`.
+ * - `duplicate_phase_id`           — Two or more phases share an `id`.
+ * - `unknown_transition_target`    — A phase transitions to an `id`
+ *                                    that doesn't appear in
+ *                                    `workflow.phases`.
+ * - `unreachable_phase`            — A phase isn't reachable from
+ *                                    `workflow.initialPhase` via the
+ *                                    transition graph.
+ * - `duplicate_persona_role`       — Two `personaBindings` share a
+ *                                    `role`.
+ * - `unknown_opportunity_phase`    — A `concurrentOpportunities` entry's
+ *                                    `attachedToPhases` references an
+ *                                    `id` not in `workflow.phases`.
+ * - `unknown_award_dimension`      — A `scoring.awards` entry's
+ *                                    `dimensionId` doesn't match any
+ *                                    `scoring.dimensions[].id`.
+ */
+export type ValidationErrorCode =
+  | 'schema'
+  | 'unknown_initial_phase'
+  | 'duplicate_phase_id'
+  | 'unknown_transition_target'
+  | 'unreachable_phase'
+  | 'duplicate_persona_role'
+  | 'unknown_opportunity_phase'
+  | 'unknown_award_dimension'
+  | 'unknown_side_effect_scoring_dimension'
+  | 'unknown_side_effect_persona_binding';
+
+export type ValidationError = {
+  readonly code: ValidationErrorCode;
+  /**
+   * Dotted path into the manifest, e.g.
+   * `['workflow', 'phases', 2, 'transitions', 0, 'to']`. Mirrors
+   * `ZodIssue.path` so a downstream renderer can treat both error
+   * sources uniformly.
+   */
+  readonly path: readonly (string | number)[];
+  readonly message: string;
+};
+
+const fromZodIssue = (issue: ZodIssue): ValidationError => ({
+  code: 'schema',
+  path: [...issue.path],
+  message: issue.message,
+});
+
+// -----------------------------------------------------------------------------
+// Structural checks
+// -----------------------------------------------------------------------------
+
+const checkPhaseIdsUnique = (
+  workflow: Workflow,
+  out: ValidationError[],
+): ReadonlySet<string> => {
+  const seen = new Set<string>();
+  const duplicates = new Set<string>();
+  for (let i = 0; i < workflow.phases.length; i += 1) {
+    const phase = workflow.phases[i];
+    if (!phase) continue;
+    if (seen.has(phase.id)) {
+      duplicates.add(phase.id);
+      out.push({
+        code: 'duplicate_phase_id',
+        path: ['workflow', 'phases', i, 'id'],
+        message: `duplicate phase id '${phase.id}'`,
+      });
+    } else {
+      seen.add(phase.id);
+    }
+  }
+  // The "valid id set" excludes duplicates so subsequent checks (e.g.
+  // transition-target resolution) don't accidentally rely on a
+  // duplicate id.
+  for (const dup of duplicates) seen.delete(dup);
+  return seen;
+};
+
+const checkInitialPhase = (
+  workflow: Workflow,
+  validIds: ReadonlySet<string>,
+  out: ValidationError[],
+): void => {
+  if (!validIds.has(workflow.initialPhase)) {
+    out.push({
+      code: 'unknown_initial_phase',
+      path: ['workflow', 'initialPhase'],
+      message: `initialPhase '${workflow.initialPhase}' is not declared in workflow.phases`,
+    });
+  }
+};
+
+const checkTransitionTargets = (
+  workflow: Workflow,
+  validIds: ReadonlySet<string>,
+  out: ValidationError[],
+): void => {
+  for (let i = 0; i < workflow.phases.length; i += 1) {
+    const phase = workflow.phases[i];
+    if (!phase) continue;
+    for (let j = 0; j < phase.transitions.length; j += 1) {
+      const transition = phase.transitions[j];
+      if (!transition) continue;
+      if (!validIds.has(transition.to)) {
+        out.push({
+          code: 'unknown_transition_target',
+          path: ['workflow', 'phases', i, 'transitions', j, 'to'],
+          message: `transition target '${transition.to}' is not a declared phase id`,
+        });
+      }
+    }
+  }
+};
+
+const checkReachability = (
+  workflow: Workflow,
+  validIds: ReadonlySet<string>,
+  out: ValidationError[],
+): void => {
+  // Skip reachability if the initial phase itself is unknown — every
+  // phase would trivially appear unreachable, and the operator already
+  // has the `unknown_initial_phase` error to act on.
+  if (!validIds.has(workflow.initialPhase)) return;
+
+  const adjacency = new Map<string, readonly string[]>();
+  for (const phase of workflow.phases) {
+    if (!validIds.has(phase.id)) continue;
+    adjacency.set(
+      phase.id,
+      phase.transitions.map((t) => t.to).filter((to) => validIds.has(to)),
+    );
+  }
+
+  const reached = new Set<string>();
+  const stack: string[] = [workflow.initialPhase];
+  while (stack.length > 0) {
+    const cur = stack.pop();
+    if (cur === undefined) break;
+    if (reached.has(cur)) continue;
+    reached.add(cur);
+    const nexts = adjacency.get(cur);
+    if (!nexts) continue;
+    for (const next of nexts) {
+      if (!reached.has(next)) stack.push(next);
+    }
+  }
+
+  for (let i = 0; i < workflow.phases.length; i += 1) {
+    const phase = workflow.phases[i];
+    if (!phase) continue;
+    if (!validIds.has(phase.id)) continue;
+    if (!reached.has(phase.id)) {
+      out.push({
+        code: 'unreachable_phase',
+        path: ['workflow', 'phases', i, 'id'],
+        message: `phase '${phase.id}' is unreachable from initialPhase '${workflow.initialPhase}'`,
+      });
+    }
+  }
+};
+
+const checkPersonaRolesUnique = (
+  bindings: readonly PersonaBinding[],
+  out: ValidationError[],
+): void => {
+  const seen = new Set<string>();
+  for (let i = 0; i < bindings.length; i += 1) {
+    const binding = bindings[i];
+    if (!binding) continue;
+    if (seen.has(binding.role)) {
+      out.push({
+        code: 'duplicate_persona_role',
+        path: ['personaBindings', i, 'role'],
+        message: `duplicate persona role '${binding.role}'`,
+      });
+    } else {
+      seen.add(binding.role);
+    }
+  }
+};
+
+const checkOpportunityPhases = (
+  opportunities: readonly ConcurrentOpportunity[],
+  validIds: ReadonlySet<string>,
+  out: ValidationError[],
+): void => {
+  for (let i = 0; i < opportunities.length; i += 1) {
+    const opp = opportunities[i];
+    if (!opp) continue;
+    for (let j = 0; j < opp.attachedToPhases.length; j += 1) {
+      const phaseId = opp.attachedToPhases[j];
+      if (phaseId === undefined) continue;
+      if (!validIds.has(phaseId)) {
+        out.push({
+          code: 'unknown_opportunity_phase',
+          path: ['concurrentOpportunities', i, 'attachedToPhases', j],
+          message: `concurrent opportunity '${opp.id}' attaches to unknown phase '${phaseId}'`,
+        });
+      }
+    }
+  }
+};
+
+const checkAwardDimensions = (
+  awards: readonly AwardDefinition[],
+  dimensionIds: ReadonlySet<string>,
+  out: ValidationError[],
+): void => {
+  for (let i = 0; i < awards.length; i += 1) {
+    const award = awards[i];
+    if (!award) continue;
+    if (!dimensionIds.has(award.dimensionId)) {
+      out.push({
+        code: 'unknown_award_dimension',
+        path: ['scoring', 'awards', i, 'dimensionId'],
+        message: `award '${award.id}' references unknown scoring dimension '${award.dimensionId}'`,
+      });
+    }
+  }
+};
+
+/**
+ * Chunk B8c — cross-check `phase.sideEffects` entries.
+ *
+ *   - `scoring` side effects reference a `scoring.dimensions[].id`
+ *     (mirrors the {@link checkAwardDimensions} check, just shifted
+ *     to the per-phase side-effect surface).
+ *   - `persona_memory` side effects reference a persona id that
+ *     appears in `personaBindings[].personaId`. If the binding is
+ *     missing the Runtime would log an `unbound_persona` event at
+ *     dispatch time; catching it at manifest validation surfaces
+ *     the error at publish time instead.
+ *
+ * `state_write` and `inference` side effects have no cross-field
+ * dependencies the manifest layer can check — the JSON-Patch ops are
+ * validated against per-Experience state schemas at apply time, and
+ * `inference.callKind` is enum-pinned at the schema level already.
+ */
+const checkPhaseSideEffects = (
+  phases: readonly ManifestPhase[],
+  dimensionIds: ReadonlySet<string>,
+  personaIds: ReadonlySet<string>,
+  out: ValidationError[],
+): void => {
+  for (let i = 0; i < phases.length; i += 1) {
+    const phase = phases[i];
+    if (!phase) continue;
+    for (let j = 0; j < phase.sideEffects.length; j += 1) {
+      const effect = phase.sideEffects[j];
+      if (!effect) continue;
+      if (effect.kind === 'scoring') {
+        if (!dimensionIds.has(effect.dimension)) {
+          out.push({
+            code: 'unknown_side_effect_scoring_dimension',
+            path: [
+              'workflow',
+              'phases',
+              i,
+              'sideEffects',
+              j,
+              'dimension',
+            ],
+            message: `phase '${phase.id}' scoring side effect references unknown dimension '${effect.dimension}'`,
+          });
+        }
+      } else if (effect.kind === 'persona_memory') {
+        if (!personaIds.has(effect.personaId)) {
+          out.push({
+            code: 'unknown_side_effect_persona_binding',
+            path: [
+              'workflow',
+              'phases',
+              i,
+              'sideEffects',
+              j,
+              'personaId',
+            ],
+            message: `phase '${phase.id}' persona_memory side effect references unbound persona '${effect.personaId}'`,
+          });
+        }
+      }
+    }
+  }
+};
+
+// -----------------------------------------------------------------------------
+// Public entrypoint
+// -----------------------------------------------------------------------------
+
+/**
+ * Validate a candidate manifest blob.
+ *
+ * Returns `Ok(manifest)` only if the Zod parse succeeds AND every
+ * structural check passes. On any failure, returns `Err([...errors])`
+ * with at least one entry — schema errors and structural errors are
+ * reported together so a UI can surface them in one round-trip.
+ *
+ * Note: when the Zod parse fails the structural checks are skipped
+ * (the manifest doesn't have a parseable shape to traverse). Schema
+ * errors are emitted in source order from the underlying Zod issue
+ * list; structural errors follow in declaration order.
+ */
+export const validateManifest = (
+  candidate: unknown,
+): Result<Manifest, readonly ValidationError[]> => {
+  const parsed = ManifestSchema.safeParse(candidate);
+  if (!parsed.success) {
+    return err(parsed.error.issues.map(fromZodIssue));
+  }
+
+  const manifest = parsed.data;
+  const errors: ValidationError[] = [];
+
+  const validIds = checkPhaseIdsUnique(manifest.workflow, errors);
+  checkInitialPhase(manifest.workflow, validIds, errors);
+  checkTransitionTargets(manifest.workflow, validIds, errors);
+  checkReachability(manifest.workflow, validIds, errors);
+  checkPersonaRolesUnique(manifest.personaBindings, errors);
+  checkOpportunityPhases(
+    manifest.concurrentOpportunities,
+    validIds,
+    errors,
+  );
+  const dimensionIds = new Set(
+    manifest.scoring.dimensions.map((d) => d.id),
+  );
+  checkAwardDimensions(manifest.scoring.awards, dimensionIds, errors);
+  const personaIds = new Set(
+    manifest.personaBindings.map((b) => b.personaId),
+  );
+  checkPhaseSideEffects(
+    manifest.workflow.phases,
+    dimensionIds,
+    personaIds,
+    errors,
+  );
+
+  if (errors.length > 0) return err(errors);
+  return ok(manifest);
+};