@svadmin/core 0.59.0 → 0.61.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svadmin/core",
-  "version": "0.59.0",
+  "version": "0.61.0",
   "author": "zuohuadong",
   "repository": {
     "type": "git",
@@ -111,6 +111,26 @@
       "types": "./src/inferencer-graphql.ts",
       "default": "./src/inferencer-graphql.ts"
     },
+    "./product-plan": {
+      "types": "./src/product-plan.ts",
+      "default": "./src/product-plan.ts"
+    },
+    "./product-navigation": {
+      "types": "./src/product-navigation.ts",
+      "default": "./src/product-navigation.ts"
+    },
+    "./product-pages": {
+      "types": "./src/product-pages.ts",
+      "default": "./src/product-pages.ts"
+    },
+    "./product-pipeline": {
+      "types": "./src/product-pipeline.ts",
+      "default": "./src/product-pipeline.ts"
+    },
+    "./product-review": {
+      "types": "./src/product-review.ts",
+      "default": "./src/product-review.ts"
+    },
     "./admin-tool": {
       "types": "./src/admin-tool.ts",
       "default": "./src/admin-tool.ts"

package/src/index.ts

@@ -304,7 +304,7 @@ export {
   generateComponentCode,
   generateResourceBundle,
 } from './inferencer';
-export type { InferResult } from './inferencer';
+export type { InferResult, InferReview, InferReviewWarning, InferReviewWarningCode } from './inferencer';
 export { createWebSocketLiveProvider } from './live-websocket';
 export type { WebSocketLiveProviderOptions } from './live-websocket';
 export { createSSELiveProvider } from './live-sse';
@@ -348,3 +348,46 @@ export type {
 // HTTP fetch utilities
 export { createFetchWithInterceptor, fetchWithInterceptor } from './http';
 export type { FetchWithInterceptor, FetchWithInterceptorOptions } from './http';
+
+// Product planning contracts keep business decisions separate from resources, pages and menus.
+export {
+  PRODUCT_PLAN_SCHEMA_VERSION,
+  ProductPlanValidationError,
+  parseProductPlan,
+  validateProductPlan,
+} from './product-plan';
+export type {
+  ProductAction,
+  ProductBrief,
+  ProductDisclosure,
+  ProductField,
+  ProductFrequency,
+  ProductId,
+  ProductMenuNode,
+  ProductMenuPlacement,
+  ProductNavigationNode,
+  ProductPageKind,
+  ProductPlan,
+  ProductPlanValidationIssue,
+  ProductPlanValidationResult,
+  ProductPriority,
+  ProductResource,
+  ProductRole,
+  ProductSurface,
+  ProductWorkflow,
+} from './product-plan';
+export {
+  buildProductNavigation,
+  flattenVisibleProductNavigation,
+  buildProductMenuItems,
+} from './product-navigation';
+export type {
+  ProductNavigationContext,
+  ProductMenuOptions,
+} from './product-navigation';
+export { buildProductPagePlan } from './product-pages';
+export type { ProductPagePlan, ProductPageSection } from './product-pages';
+export { formatProductPreview, runProductPipeline } from './product-pipeline';
+export type { ProductPipelineInput, ProductPipelineOutput } from './product-pipeline';
+export { reviewProductPlan } from './product-review';
+export type { ProductReviewIssue, ProductReviewMetrics, ProductReviewReport, ProductReviewSeverity } from './product-review';

package/src/inferencer.ts

@@ -84,6 +84,7 @@ export interface InferResult {
   resource: ResourceDefinition;
   code: string;
   typeboxCode: string;
+  review: InferReview;
   componentCode: {
     list: string;
     create: string;
@@ -92,6 +93,26 @@ export interface InferResult {
   };
 }
 
+export type InferReviewWarningCode =
+  | 'empty-sample'
+  | 'nullable-field'
+  | 'mixed-types'
+  | 'heuristic-relation'
+  | 'heuristic-select';
+
+export interface InferReviewWarning {
+  code: InferReviewWarningCode;
+  field?: string;
+  message: string;
+}
+
+export interface InferReview {
+  needsReview: boolean;
+  confidence: 'high' | 'medium' | 'low';
+  sampleSize: number;
+  warnings: InferReviewWarning[];
+}
+
 /**
  * Analyze a sample data array and produce a ResourceDefinition.
  * @param resourceName - Name of the resource (e.g. "posts")
@@ -116,6 +137,15 @@ export function inferResource(
       resource: emptyResource,
       code: `// No data available to infer fields for "${resourceName}".`,
       typeboxCode: generateTypeBoxSchemaCode(emptyResource),
+      review: {
+        needsReview: true,
+        confidence: 'low',
+        sampleSize: 0,
+        warnings: [{
+          code: 'empty-sample',
+          message: `No sample records were available for "${resourceName}".`,
+        }],
+      },
       componentCode: {
         list: generateListPageCode(emptyResource),
         create: generateCreatePageCode(emptyResource),
@@ -133,6 +163,7 @@ export function inferResource(
 
   // For each key, infer from all non-null values
   const fields: FieldDefinition[] = [];
+  const warnings: InferReviewWarning[] = [];
   for (const key of keySet) {
     // Collect non-null values
     const values = sampleData
@@ -141,6 +172,13 @@ export function inferResource(
 
     const sampleValue = values[0];
     let inferredType = inferFieldType(key, sampleValue);
+    if (values.length === 0) {
+      warnings.push({
+        code: 'nullable-field',
+        field: key,
+        message: `Field "${key}" contains only null or undefined values in the sample.`,
+      });
+    }
 
     // Cross-validate: if most values for this key are of a different type, use majority
     const typeCounts = new Map<InferredType, number>();
@@ -155,13 +193,34 @@ export function inferResource(
         inferredType = t;
       }
     }
+    if (typeCounts.size > 1) {
+      warnings.push({
+        code: 'mixed-types',
+        field: key,
+        message: `Field "${key}" contains multiple inferred types; the majority type was selected.`,
+      });
+    }
 
     // Check for relation
     const relatedResource = isLikelyRelation(key);
+    if (relatedResource) {
+      warnings.push({
+        code: 'heuristic-relation',
+        field: key,
+        message: `Relation "${key}" was inferred from its field name.`,
+      });
+    }
 
     // Check if it looks like a select (few unique string values)
     const uniqueStrings = new Set(values.filter(v => typeof v === 'string') as string[]);
     const isSelect = inferredType === 'text' && uniqueStrings.size > 1 && uniqueStrings.size <= 10 && values.length >= 5;
+    if (isSelect) {
+      warnings.push({
+        code: 'heuristic-select',
+        field: key,
+        message: `Select options for "${key}" were inferred from repeated sample values.`,
+      });
+    }
 
     const field: FieldDefinition = {
       key,
@@ -213,7 +272,23 @@ export function inferResource(
     show: generateShowPageCode(resource),
   };
 
-  return { fields, resource, code, typeboxCode, componentCode };
+  return {
+    fields,
+    resource,
+    code,
+    typeboxCode,
+    review: {
+      needsReview: warnings.length > 0,
+      confidence: warnings.some((warning) => warning.code === 'mixed-types' || warning.code === 'nullable-field')
+        ? 'low'
+        : warnings.length > 0
+          ? 'medium'
+          : 'high',
+      sampleSize: sampleData.length,
+      warnings,
+    },
+    componentCode,
+  };
 }
 
 // ─── Code Generation ─────────────────────────────────────────
@@ -462,6 +537,12 @@ export function generateResourceBundle(resource: ResourceDefinition): InferResul
     resource,
     code: generateResourceCode(resource),
     typeboxCode: generateTypeBoxSchemaCode(resource),
+    review: {
+      needsReview: false,
+      confidence: 'high',
+      sampleSize: 0,
+      warnings: [],
+    },
     componentCode: {
       list: generateListPageCode(resource),
       create: generateCreatePageCode(resource),

package/src/product-navigation.ts

@@ -0,0 +1,145 @@
+import type { MenuItem } from './types';
+import type {
+  ProductMenuNode,
+  ProductMenuPlacement,
+  ProductNavigationNode,
+  ProductPlan,
+  ProductSurface,
+} from './product-plan';
+
+export interface ProductNavigationContext {
+  readonly roleIds: readonly string[];
+  readonly featureFlags?: Readonly<Record<string, boolean>>;
+}
+
+export interface ProductMenuOptions {
+  /**
+   * Placements that may become sidebar menu items. Contextual and command
+   * entries stay out of the persistent navigation unless explicitly opted in.
+   */
+  readonly includePlacements?: readonly ProductMenuPlacement[];
+}
+
+const DEFAULT_MENU_PLACEMENTS: readonly ProductMenuPlacement[] = ['primary', 'secondary', 'settings'];
+
+function canSeeByRole(item: ProductMenuNode, roleIds: readonly string[]): boolean {
+  // Empty roleIds means the entry is public at the UI hint layer. Backend authorization remains authoritative.
+  return item.roleIds.length === 0 || item.roleIds.some(roleId => roleIds.includes(roleId));
+}
+
+function conditionEnabled(condition: string | undefined, flags: Readonly<Record<string, boolean>> | undefined): boolean {
+  return condition === undefined ? true : flags?.[condition] === true;
+}
+
+function createNode(
+  item: ProductMenuNode,
+  allItems: readonly ProductMenuNode[],
+  context: ProductNavigationContext,
+  ancestry: ReadonlySet<string> = new Set(),
+): ProductNavigationNode {
+  const visibleByRole = canSeeByRole(item, context.roleIds);
+  const visibleByCondition = conditionEnabled(item.condition, context.featureFlags);
+  const visible = visibleByRole && visibleByCondition && item.placement !== 'hidden';
+  const nextAncestry = new Set(ancestry);
+  nextAncestry.add(item.id);
+  const children = nextAncestry.has(item.id)
+    ? allItems
+      .filter(candidate => candidate.parentId === item.id && !nextAncestry.has(candidate.id))
+      .sort((left, right) => (left.order ?? 0) - (right.order ?? 0))
+      .map(candidate => createNode(candidate, allItems, context, nextAncestry))
+    : [];
+  return {
+    ...item,
+    children,
+    visible,
+    ...(visible ? {} : { reason: visibleByRole ? 'hidden by business condition or placement' : 'current role is not allowed to see this entry' }),
+  };
+}
+
+/**
+ * Builds a product navigation tree from product decisions. There is
+ * deliberately no fixed menu count: domain complexity determines the number
+ * of entries, while review checks whether each entry has a role, workflow,
+ * resource or surface target.
+ */
+export function buildProductNavigation(plan: ProductPlan, context: ProductNavigationContext): ProductNavigationNode[] {
+  return plan.menu
+    .filter(item => item.parentId === undefined)
+    .sort((left, right) => (left.order ?? 0) - (right.order ?? 0))
+    .map(item => createNode(item, plan.menu, context));
+}
+
+export function flattenVisibleProductNavigation(nodes: readonly ProductNavigationNode[]): ProductNavigationNode[] {
+  return nodes.flatMap(node => node.visible
+    ? [node, ...flattenVisibleProductNavigation(node.children)]
+    : []);
+}
+
+function surfaceRoute(surface: ProductSurface | undefined): string | undefined {
+  if (surface === undefined) return undefined;
+  // route is optional so older product/v1 plans keep a stable generated URL.
+  const route = (surface as ProductSurface & { readonly route?: string }).route;
+  return route ?? `/workflows/${surface.id}`;
+}
+
+function resourceName(plan: ProductPlan, resourceId: string | undefined): string | undefined {
+  if (resourceId === undefined) return undefined;
+  const resource = plan.resources.find(candidate => candidate.id === resourceId);
+  return resource?.runtimeName ?? resource?.name;
+}
+
+function menuHref(
+  plan: ProductPlan,
+  node: ProductNavigationNode,
+  surfaces: ReadonlyMap<string, ProductSurface>,
+): string | undefined {
+  if (node.href !== undefined) return node.href;
+  const bySurface = surfaceRoute(surfaces.get(node.surfaceId ?? ''));
+  if (bySurface !== undefined) return bySurface;
+  const byResource = resourceName(plan, node.resourceId);
+  return byResource === undefined ? undefined : `/${byResource}`;
+}
+
+function toMenuItem(
+  plan: ProductPlan,
+  node: ProductNavigationNode,
+  surfaces: ReadonlyMap<string, ProductSurface>,
+  placements: readonly ProductMenuPlacement[],
+): MenuItem | undefined {
+  // Do not promote a visible child when its parent is hidden or filtered out.
+  // Hidden parents represent an intentional product decision and their subtree
+  // should not become orphaned sidebar entries.
+  if (!node.visible || !placements.includes(node.placement)) return undefined;
+
+  const children = node.children
+    .map(child => toMenuItem(plan, child, surfaces, placements))
+    .filter((child): child is MenuItem => child !== undefined);
+  const href = menuHref(plan, node, surfaces);
+  const targetResource = resourceName(plan, node.resourceId);
+  const menuItem: MenuItem = {
+    name: node.id,
+    ...(node.label.length > 0 ? { label: node.label } : {}),
+    ...(node.icon !== undefined ? { icon: node.icon } : {}),
+    ...(href !== undefined ? { href } : {}),
+    ...(targetResource !== undefined ? { meta: { resource: targetResource } } : {}),
+    ...(children.length > 0 ? { children } : {}),
+  };
+  return menuItem;
+}
+
+/**
+ * Adapts product navigation metadata to the core MenuItem contract used by
+ * AdminApp, Lite and the sidebar. Role and feature filtering happen before
+ * conversion, and only requested placements become persistent menu items.
+ */
+export function buildProductMenuItems(
+  plan: ProductPlan,
+  context: ProductNavigationContext,
+  options: ProductMenuOptions = {},
+): MenuItem[] {
+  const placements = options.includePlacements ?? DEFAULT_MENU_PLACEMENTS;
+  const surfaces = new Map(plan.surfaces.map(surface => [surface.id, surface] as const));
+  return buildProductNavigation(plan, context)
+    .map(node => toMenuItem(plan, node, surfaces, placements))
+    .filter((item): item is MenuItem => item !== undefined);
+}

package/src/product-pages.ts

@@ -0,0 +1,45 @@
+import type { ProductAction, ProductPlan, ProductSurface } from './product-plan';
+
+export interface ProductPageSection {
+  readonly id: string;
+  readonly title: string;
+  readonly resourceIds: readonly string[];
+}
+
+export interface ProductPagePlan {
+  readonly id: string;
+  readonly kind: ProductSurface['kind'];
+  readonly title: string;
+  readonly purpose: string;
+  readonly workflowIds: readonly string[];
+  readonly roleIds: readonly string[];
+  readonly primaryAction?: ProductAction;
+  readonly secondaryActions: readonly ProductAction[];
+  readonly sections: readonly ProductPageSection[];
+  readonly states: ProductSurface['states'];
+}
+
+/** Generates a small, renderer-neutral page plan for Svelte components. */
+export function buildProductPagePlan(surface: ProductSurface, plan: ProductPlan): ProductPagePlan {
+  const actionById = new Map(plan.actions.map(action => [action.id, action]));
+  const primaryAction = surface.primaryActionId === undefined ? undefined : actionById.get(surface.primaryActionId);
+  const secondaryActions = surface.actionIds
+    .filter(id => id !== surface.primaryActionId)
+    .map(id => actionById.get(id))
+    .filter((action): action is ProductAction => action !== undefined);
+  const sections = surface.sections.length
+    ? surface.sections.map((title, index) => ({ id: `${surface.id}.section.${index + 1}`, title, resourceIds: surface.resourceIds }))
+    : [{ id: `${surface.id}.content`, title: surface.name, resourceIds: surface.resourceIds }];
+  return {
+    id: surface.id,
+    kind: surface.kind,
+    title: surface.name,
+    purpose: surface.purpose,
+    workflowIds: surface.workflowIds,
+    roleIds: surface.roleIds,
+    ...(primaryAction === undefined ? {} : { primaryAction }),
+    secondaryActions,
+    sections,
+    states: surface.states,
+  };
+}

package/src/product-pipeline.ts

@@ -0,0 +1,43 @@
+import type { ProductNavigationNode, ProductPlan } from './product-plan';
+import { buildProductNavigation, type ProductNavigationContext } from './product-navigation';
+import { buildProductPagePlan, type ProductPagePlan } from './product-pages';
+import { reviewProductPlan, type ProductReviewReport } from './product-review';
+
+export interface ProductPipelineInput {
+  readonly plan: ProductPlan;
+  readonly navigation: ProductNavigationContext;
+  readonly surfaceIds?: readonly string[];
+}
+
+export interface ProductPipelineOutput {
+  readonly navigation: readonly ProductNavigationNode[];
+  readonly pages: readonly ProductPagePlan[];
+  readonly productReview: ProductReviewReport;
+}
+
+export function runProductPipeline(input: ProductPipelineInput): ProductPipelineOutput {
+  const navigation = buildProductNavigation(input.plan, input.navigation);
+  const visibleSurfaceIds = input.surfaceIds === undefined
+    ? undefined
+    : new Set(input.surfaceIds);
+  const pages = input.plan.surfaces
+    .filter(surface => visibleSurfaceIds === undefined || visibleSurfaceIds.has(surface.id))
+    .filter(surface => surface.roleIds.length === 0 || surface.roleIds.some(roleId => input.navigation.roleIds.includes(roleId)))
+    .map(surface => buildProductPagePlan(surface, input.plan));
+  return { navigation, pages, productReview: reviewProductPlan(input.plan) };
+}
+
+export function formatProductPreview(output: ProductPipelineOutput): string {
+  const lines = ['Navigation:'];
+  for (const node of output.navigation) {
+    // A hidden parent owns its subtree; do not promote role-filtered children
+    // into a misleading top-level preview entry.
+    if (!node.visible) continue;
+    lines.push(`- ${node.label}`);
+    for (const child of node.children) if (child.visible) lines.push(`  - ${child.label}`);
+  }
+  lines.push('', 'Pages:');
+  output.pages.forEach(page => lines.push(`- ${page.title}: ${page.purpose}`));
+  lines.push('', `Product review: ${output.productReview.ok ? 'pass' : 'fail'}`);
+  return lines.join('\n');
+}

package/src/product-plan.ts

@@ -0,0 +1,359 @@
+/**
+ * Product decisions used by svadmin generation.
+ *
+ * Resource, surface, action and menu are intentionally separate concepts.
+ * A backend resource may be contextual data without becoming a page or menu item.
+ */
+export const PRODUCT_PLAN_SCHEMA_VERSION = 'product/v1' as const;
+
+export type ProductId = string;
+export type ProductPriority = 'core' | 'secondary' | 'future';
+export type ProductMenuPlacement = 'primary' | 'secondary' | 'settings' | 'context' | 'command' | 'hidden';
+export type ProductPageKind = 'workbench' | 'list' | 'detail' | 'form' | 'approval' | 'import' | 'settings' | 'custom';
+export type ProductDisclosure = 'visible' | 'collapsed' | 'more' | 'context' | 'hidden';
+export type ProductFrequency = 'high' | 'medium' | 'low' | 'unknown';
+
+export interface ProductBrief {
+  readonly id: ProductId;
+  readonly name: string;
+  readonly description: string;
+  readonly primaryOutcome: string;
+  readonly primaryAudience: string;
+  readonly constraints: readonly string[];
+  readonly nonGoals: readonly string[];
+  readonly assumptions: readonly string[];
+}
+
+export interface ProductRole {
+  readonly id: ProductId;
+  readonly name: string;
+  readonly description?: string;
+  readonly permissions: readonly string[];
+}
+
+export interface ProductWorkflow {
+  readonly id: ProductId;
+  readonly name: string;
+  readonly actorRoleIds: readonly ProductId[];
+  readonly trigger: string;
+  readonly goal: string;
+  readonly steps: readonly string[];
+  readonly successCriteria: readonly string[];
+  readonly exceptions: readonly string[];
+  readonly priority: ProductPriority;
+  readonly frequency: ProductFrequency;
+}
+
+export interface ProductField {
+  readonly id: ProductId;
+  readonly label: string;
+  readonly type: string;
+  readonly required?: boolean;
+  readonly readableBy: readonly ProductId[];
+  readonly writableBy: readonly ProductId[];
+  readonly usedByWorkflowIds: readonly ProductId[];
+  readonly disclosure?: ProductDisclosure;
+  readonly sensitive?: boolean;
+}
+
+export interface ProductResource {
+  readonly id: ProductId;
+  readonly name: string;
+  readonly label: string;
+  readonly description?: string;
+  readonly runtimeName?: string;
+  readonly fields: readonly ProductField[];
+  readonly menuPlacement?: ProductMenuPlacement;
+  readonly roleIds: readonly ProductId[];
+  readonly workflowIds: readonly ProductId[];
+  readonly internal?: boolean;
+}
+
+export interface ProductAction {
+  readonly id: ProductId;
+  readonly label: string;
+  readonly description?: string;
+  readonly workflowId: ProductId;
+  readonly roleIds: readonly ProductId[];
+  readonly disclosure?: ProductDisclosure;
+  readonly destructive?: boolean;
+  readonly condition?: string;
+}
+
+export interface ProductSurface {
+  readonly id: ProductId;
+  readonly name: string;
+  readonly kind: ProductPageKind;
+  readonly purpose: string;
+  /** Optional stable route. Generators derive one when omitted. */
+  readonly route?: string;
+  readonly workflowIds: readonly ProductId[];
+  readonly resourceIds: readonly ProductId[];
+  readonly roleIds: readonly ProductId[];
+  readonly menuPlacement?: ProductMenuPlacement;
+  readonly parentSurfaceId?: ProductId;
+  readonly primaryActionId?: ProductId;
+  readonly actionIds: readonly ProductId[];
+  readonly sections: readonly string[];
+  readonly states: readonly ('empty' | 'loading' | 'error' | 'forbidden' | 'success')[];
+}
+
+export interface ProductMenuNode {
+  readonly id: ProductId;
+  readonly label: string;
+  readonly icon?: string;
+  readonly href?: string;
+  readonly surfaceId?: ProductId;
+  readonly resourceId?: ProductId;
+  readonly workflowIds: readonly ProductId[];
+  readonly roleIds: readonly ProductId[];
+  readonly placement: ProductMenuPlacement;
+  readonly parentId?: ProductId;
+  readonly condition?: string;
+  readonly order?: number;
+}
+
+export interface ProductPlan {
+  readonly schemaVersion: typeof PRODUCT_PLAN_SCHEMA_VERSION;
+  readonly brief: ProductBrief;
+  readonly roles: readonly ProductRole[];
+  readonly workflows: readonly ProductWorkflow[];
+  readonly resources: readonly ProductResource[];
+  readonly actions: readonly ProductAction[];
+  readonly surfaces: readonly ProductSurface[];
+  readonly menu: readonly ProductMenuNode[];
+}
+
+export interface ProductPlanValidationIssue {
+  readonly code: 'invalid-root' | 'invalid-version' | 'missing-array' | 'invalid-id' | 'invalid-field' | 'invalid-enum' | 'duplicate-id';
+  readonly path: string;
+  readonly message: string;
+}
+
+export type ProductPlanValidationResult =
+  | { readonly ok: true; readonly value: ProductPlan }
+  | { readonly ok: false; readonly issues: readonly ProductPlanValidationIssue[] };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function hasStringId(value: unknown): value is { readonly id: string } {
+  return isRecord(value) && typeof value['id'] === 'string' && value['id'].trim().length > 0;
+}
+
+const PRODUCT_DISCLOSURES = ['visible', 'collapsed', 'more', 'context', 'hidden'] as const;
+const PRODUCT_PRIORITIES = ['core', 'secondary', 'future'] as const;
+const PRODUCT_FREQUENCIES = ['high', 'medium', 'low', 'unknown'] as const;
+const PRODUCT_PLACEMENTS = ['primary', 'secondary', 'settings', 'context', 'command', 'hidden'] as const;
+const PRODUCT_PAGE_KINDS = ['workbench', 'list', 'detail', 'form', 'approval', 'import', 'settings', 'custom'] as const;
+const PRODUCT_STATES = ['empty', 'loading', 'error', 'forbidden', 'success'] as const;
+
+function pushEnumIssue(
+  issues: ProductPlanValidationIssue[],
+  value: unknown,
+  path: string,
+  allowed: readonly string[],
+): void {
+  if (typeof value !== 'string' || !allowed.includes(value)) {
+    issues.push({ code: 'invalid-enum', path, message: path + ' must be one of ' + allowed.join(', ') + '.' });
+  }
+}
+
+function pushProductFieldIssues(
+  issues: ProductPlanValidationIssue[],
+  value: unknown,
+  path: string,
+): void {
+  if (!Array.isArray(value)) {
+    issues.push({ code: 'missing-array', path, message: path + ' must be an array.' });
+    return;
+  }
+  const seen = new Set<string>();
+  value.forEach((item, index) => {
+    const itemPath = path + '.' + index;
+    if (!isRecord(item)) {
+      issues.push({ code: 'invalid-field', path: itemPath, message: itemPath + ' must be an object.' });
+      return;
+    }
+    const fieldId = item['id'];
+    if (typeof fieldId !== 'string' || fieldId.trim().length === 0) {
+      issues.push({ code: 'invalid-id', path: itemPath + '.id', message: 'Every product field needs a non-empty string id.' });
+      return;
+    }
+    if (seen.has(fieldId)) {
+      issues.push({ code: 'duplicate-id', path: itemPath + '.id', message: 'Product field id ' + fieldId + ' is duplicated within its resource.' });
+    }
+    seen.add(fieldId);
+    for (const key of ['label', 'type'] as const) {
+      if (typeof item[key] !== 'string') issues.push({ code: 'invalid-field', path: itemPath + '.' + key, message: itemPath + '.' + key + ' must be a string.' });
+    }
+    for (const key of ['readableBy', 'writableBy', 'usedByWorkflowIds'] as const) {
+      const candidate = item[key];
+      if (!Array.isArray(candidate) || !candidate.every(entry => typeof entry === 'string')) {
+        issues.push({ code: 'invalid-field', path: itemPath + '.' + key, message: itemPath + '.' + key + ' must be an array of strings.' });
+      }
+    }
+    for (const key of ['required', 'sensitive'] as const) {
+      if (item[key] !== undefined && typeof item[key] !== 'boolean') {
+        issues.push({ code: 'invalid-field', path: itemPath + '.' + key, message: itemPath + '.' + key + ' must be a boolean when provided.' });
+      }
+    }
+    if (item['disclosure'] !== undefined) pushEnumIssue(issues, item['disclosure'], itemPath + '.disclosure', PRODUCT_DISCLOSURES);
+  });
+}
+
+interface EntityShape {
+  readonly strings?: readonly string[];
+  readonly arrays?: readonly string[];
+}
+
+function pushEntityIssues(
+  issues: ProductPlanValidationIssue[],
+  value: unknown,
+  path: string,
+  seen: Set<string>,
+  shape: EntityShape = {},
+): void {
+  if (!Array.isArray(value)) {
+    issues.push({ code: 'missing-array', path, message: `${path} must be an array.` });
+    return;
+  }
+  value.forEach((item, index) => {
+    const itemPath = `${path}.${index}`;
+    if (!hasStringId(item)) {
+      issues.push({ code: 'invalid-id', path: `${itemPath}.id`, message: 'Every product entity needs a non-empty string id.' });
+      return;
+    }
+    if (seen.has(item.id)) {
+      issues.push({ code: 'duplicate-id', path: `${itemPath}.id`, message: `Product id "${item.id}" is duplicated.` });
+    }
+    seen.add(item.id);
+    const record: Record<string, unknown> | undefined = isRecord(item) ? item : undefined;
+    if (!record) return;
+    for (const key of shape.strings ?? []) {
+      if (typeof record[key] !== 'string') issues.push({ code: 'invalid-field', path: `${itemPath}.${key}`, message: `${itemPath}.${key} must be a string.` });
+    }
+    for (const key of shape.arrays ?? []) {
+      const candidate = record[key];
+      if (!Array.isArray(candidate) || !candidate.every(value => typeof value === 'string')) {
+        issues.push({ code: 'invalid-field', path: `${itemPath}.${key}`, message: `${itemPath}.${key} must be an array of strings.` });
+      }
+    }
+  });
+}
+
+/** Validates the JSON boundary before review or generation consumes a plan. */
+export function validateProductPlan(input: unknown): ProductPlanValidationResult {
+  const issues: ProductPlanValidationIssue[] = [];
+  if (!isRecord(input)) return { ok: false, issues: [{ code: 'invalid-root', path: '', message: 'Product plan must be a JSON object.' }] };
+  if (input['schemaVersion'] !== PRODUCT_PLAN_SCHEMA_VERSION) {
+    issues.push({ code: 'invalid-version', path: 'schemaVersion', message: `Expected ${PRODUCT_PLAN_SCHEMA_VERSION}.` });
+  }
+  if (!isRecord(input['brief'])) {
+    issues.push({ code: 'invalid-root', path: 'brief', message: 'Product plan brief must be an object.' });
+  } else {
+    const brief = input['brief'] as Record<string, unknown>;
+    for (const key of ['id', 'name', 'description', 'primaryOutcome', 'primaryAudience'] as const) {
+      if (typeof brief[key] !== 'string') issues.push({ code: 'invalid-field', path: `brief.${key}`, message: `brief.${key} must be a string.` });
+    }
+    for (const key of ['constraints', 'nonGoals', 'assumptions'] as const) {
+      const candidate = brief[key];
+      if (!Array.isArray(candidate) || !candidate.every((value: unknown) => typeof value === 'string')) issues.push({ code: 'invalid-field', path: `brief.${key}`, message: `brief.${key} must be an array of strings.` });
+    }
+  }
+  const shapes: Record<string, EntityShape> = {
+    roles: { strings: ['name'], arrays: ['permissions'] },
+    workflows: { strings: ['name', 'trigger', 'goal', 'priority', 'frequency'], arrays: ['actorRoleIds', 'steps', 'successCriteria', 'exceptions'] },
+    resources: { strings: ['name', 'label'], arrays: ['roleIds', 'workflowIds'] },
+    actions: { strings: ['label', 'workflowId'], arrays: ['roleIds'] },
+    surfaces: { strings: ['name', 'kind', 'purpose'], arrays: ['workflowIds', 'resourceIds', 'roleIds', 'actionIds', 'sections', 'states'] },
+    menu: { strings: ['label', 'placement'], arrays: ['workflowIds', 'roleIds'] },
+  };
+  for (const key of ['roles', 'workflows', 'resources', 'actions', 'surfaces', 'menu'] as const) {
+    // IDs are scoped to their entity collection. Cross-entity references are
+    // explicit (for example resourceIds and workflowIds), so a menu entry may
+    // intentionally share a label-like ID with its target resource or surface.
+    pushEntityIssues(issues, input[key], key, new Set<string>(), shapes[key]);
+  }
+
+  const workflows = input['workflows'];
+  if (Array.isArray(workflows)) workflows.forEach((workflow, index) => {
+    if (!isRecord(workflow)) return;
+    if (typeof workflow['priority'] === 'string') pushEnumIssue(issues, workflow['priority'], 'workflows.' + index + '.priority', PRODUCT_PRIORITIES);
+    if (typeof workflow['frequency'] === 'string') pushEnumIssue(issues, workflow['frequency'], 'workflows.' + index + '.frequency', PRODUCT_FREQUENCIES);
+  });
+
+  const resources = input['resources'];
+  if (Array.isArray(resources)) resources.forEach((resource, index) => {
+    if (!isRecord(resource)) return;
+    pushProductFieldIssues(issues, resource['fields'], 'resources.' + index + '.fields');
+    if (resource['menuPlacement'] !== undefined) pushEnumIssue(issues, resource['menuPlacement'], 'resources.' + index + '.menuPlacement', PRODUCT_PLACEMENTS);
+    if (resource['internal'] !== undefined && typeof resource['internal'] !== 'boolean') {
+      issues.push({ code: 'invalid-field', path: 'resources.' + index + '.internal', message: 'resources.' + index + '.internal must be a boolean when provided.' });
+    }
+  });
+
+  const actions = input['actions'];
+  if (Array.isArray(actions)) actions.forEach((action, index) => {
+    if (!isRecord(action)) return;
+    if (action['disclosure'] !== undefined) pushEnumIssue(issues, action['disclosure'], 'actions.' + index + '.disclosure', PRODUCT_DISCLOSURES);
+    if (action['destructive'] !== undefined && typeof action['destructive'] !== 'boolean') {
+      issues.push({ code: 'invalid-field', path: 'actions.' + index + '.destructive', message: 'actions.' + index + '.destructive must be a boolean when provided.' });
+    }
+  });
+
+  const surfaces = input['surfaces'];
+  if (Array.isArray(surfaces)) surfaces.forEach((surface, index) => {
+    if (!isRecord(surface)) return;
+    if (typeof surface['kind'] === 'string') pushEnumIssue(issues, surface['kind'], 'surfaces.' + index + '.kind', PRODUCT_PAGE_KINDS);
+    if (surface['menuPlacement'] !== undefined) pushEnumIssue(issues, surface['menuPlacement'], 'surfaces.' + index + '.menuPlacement', PRODUCT_PLACEMENTS);
+    if (surface['route'] !== undefined && (typeof surface['route'] !== 'string' || surface['route'].trim().length === 0)) {
+      issues.push({ code: 'invalid-field', path: 'surfaces.' + index + '.route', message: 'surfaces.' + index + '.route must be a non-empty string when provided.' });
+    }
+    const states = surface['states'];
+    if (Array.isArray(states)) states.forEach((state, stateIndex) => {
+      if (typeof state === 'string') pushEnumIssue(issues, state, 'surfaces.' + index + '.states.' + stateIndex, PRODUCT_STATES);
+    });
+  });
+
+  const menu = input['menu'];
+  if (Array.isArray(menu)) menu.forEach((entry, index) => {
+    if (!isRecord(entry)) return;
+    if (typeof entry['placement'] === 'string') pushEnumIssue(issues, entry['placement'], 'menu.' + index + '.placement', PRODUCT_PLACEMENTS);
+    for (const key of ['href', 'parentId', 'surfaceId', 'resourceId', 'condition'] as const) {
+      if (entry[key] !== undefined && typeof entry[key] !== 'string') {
+        issues.push({ code: 'invalid-field', path: 'menu.' + index + '.' + key, message: 'menu.' + index + '.' + key + ' must be a string when provided.' });
+      }
+    }
+    if (entry['order'] !== undefined && (typeof entry['order'] !== 'number' || !Number.isFinite(entry['order']))) {
+      issues.push({ code: 'invalid-field', path: 'menu.' + index + '.order', message: 'menu.' + index + '.order must be a finite number when provided.' });
+    }
+  });
+
+  return issues.length === 0
+    ? { ok: true, value: input as unknown as ProductPlan }
+    : { ok: false, issues };
+}
+
+export class ProductPlanValidationError extends Error {
+  readonly issues: readonly ProductPlanValidationIssue[];
+
+  constructor(issues: readonly ProductPlanValidationIssue[]) {
+    super(`Invalid product plan (${issues.length} issue${issues.length === 1 ? '' : 's'})`);
+    this.name = 'ProductPlanValidationError';
+    this.issues = issues;
+  }
+}
+
+export function parseProductPlan(input: unknown): ProductPlan {
+  const result = validateProductPlan(input);
+  if (!result.ok) throw new ProductPlanValidationError(result.issues);
+  return result.value;
+}
+
+export interface ProductNavigationNode extends ProductMenuNode {
+  readonly children: readonly ProductNavigationNode[];
+  readonly visible: boolean;
+  readonly reason?: string;
+}

package/src/product-review.ts

@@ -0,0 +1,123 @@
+import type { ProductPlan, ProductSurface } from './product-plan';
+
+export type ProductReviewSeverity = 'error' | 'warning' | 'info';
+
+export interface ProductReviewIssue {
+  readonly code: string;
+  readonly severity: ProductReviewSeverity;
+  readonly message: string;
+  readonly path?: string;
+  readonly suggestion?: string;
+}
+
+export interface ProductReviewMetrics {
+  readonly resourceCount: number;
+  readonly workflowCount: number;
+  readonly surfaceCount: number;
+  readonly menuNodeCount: number;
+  readonly orphanResourceCount: number;
+  readonly unservedWorkflowCount: number;
+  readonly roleVisibilityGaps: number;
+}
+
+export interface ProductReviewReport {
+  readonly ok: boolean;
+  readonly issues: readonly ProductReviewIssue[];
+  readonly metrics: ProductReviewMetrics;
+}
+
+function has<T>(set: ReadonlySet<T>, value: T): boolean { return set.has(value); }
+function addIssue(issues: ProductReviewIssue[], issue: ProductReviewIssue): void { issues.push(issue); }
+
+export function reviewProductPlan(plan: ProductPlan): ProductReviewReport {
+  const issues: ProductReviewIssue[] = [];
+  const roleIds = new Set(plan.roles.map(role => role.id));
+  const workflowIds = new Set(plan.workflows.map(workflow => workflow.id));
+  const resourceIds = new Set(plan.resources.map(resource => resource.id));
+  const surfaceIds = new Set(plan.surfaces.map(surface => surface.id));
+  const actionIds = new Set(plan.actions.map(action => action.id));
+
+  for (const workflow of plan.workflows) {
+    if (!workflow.actorRoleIds.length) addIssue(issues, { code: 'workflow.missing-actor', severity: 'error', message: `Workflow "${workflow.name}" has no actor role.`, path: `workflows.${workflow.id}.actorRoleIds` });
+    for (const roleId of workflow.actorRoleIds) if (!has(roleIds, roleId)) addIssue(issues, { code: 'workflow.unknown-role', severity: 'error', message: `Workflow "${workflow.name}" references unknown role "${roleId}".`, path: `workflows.${workflow.id}.actorRoleIds` });
+    if (!workflow.goal.trim()) addIssue(issues, { code: 'workflow.missing-goal', severity: 'error', message: `Workflow "${workflow.name}" has no user goal.`, path: `workflows.${workflow.id}.goal` });
+  }
+
+  for (const resource of plan.resources) {
+    if (!resource.workflowIds.length && !resource.internal) addIssue(issues, { code: 'resource.no-workflow', severity: 'warning', message: `Resource "${resource.label}" is not attached to a workflow.`, path: `resources.${resource.id}.workflowIds`, suggestion: 'Make it contextual/internal or attach it to a real task.' });
+    for (const workflowId of resource.workflowIds) if (!has(workflowIds, workflowId)) addIssue(issues, { code: 'resource.unknown-workflow', severity: 'error', message: `Resource "${resource.label}" references unknown workflow "${workflowId}".`, path: `resources.${resource.id}.workflowIds` });
+  }
+
+  for (const surface of plan.surfaces) {
+    reviewSurface(surface, { workflowIds, actionIds, resourceIds }, issues);
+  }
+
+  const menuById = new Map(plan.menu.map(item => [item.id, item] as const));
+  for (const item of plan.menu) {
+    if (item.parentId !== undefined && !menuById.has(item.parentId)) {
+      addIssue(issues, { code: 'menu.unknown-parent', severity: 'error', message: `Menu item "${item.label}" references unknown parent "${item.parentId}".`, path: `menu.${item.id}.parentId` });
+    }
+  }
+  const visiting = new Set<string>();
+  const visited = new Set<string>();
+  const visitMenu = (id: string): void => {
+    if (visiting.has(id)) {
+      addIssue(issues, { code: 'menu.cycle', severity: 'error', message: `Menu hierarchy contains a cycle at "${id}".`, path: `menu.${id}.parentId` });
+      return;
+    }
+    if (visited.has(id)) return;
+    visiting.add(id);
+    const parentId = menuById.get(id)?.parentId;
+    if (parentId !== undefined && menuById.has(parentId)) visitMenu(parentId);
+    visiting.delete(id);
+    visited.add(id);
+  };
+  for (const item of plan.menu) visitMenu(item.id);
+
+  for (const item of plan.menu) {
+    if (!item.workflowIds.length && !item.resourceId && !item.surfaceId) addIssue(issues, { code: 'menu.no-business-target', severity: 'warning', message: `Menu item "${item.label}" has no workflow, resource or surface target.`, path: `menu.${item.id}`, suggestion: 'Keep it only for an intentional external/system entry.' });
+    if (item.surfaceId && !has(surfaceIds, item.surfaceId)) addIssue(issues, { code: 'menu.unknown-surface', severity: 'error', message: `Menu item "${item.label}" references unknown surface.`, path: `menu.${item.id}.surfaceId` });
+    if (item.resourceId && !has(resourceIds, item.resourceId)) addIssue(issues, { code: 'menu.unknown-resource', severity: 'error', message: `Menu item "${item.label}" references unknown resource.`, path: `menu.${item.id}.resourceId` });
+    if (!item.roleIds.length && item.placement !== 'hidden') addIssue(issues, { code: 'menu.public-entry', severity: 'info', message: `Menu item "${item.label}" is public at the UI hint layer.`, path: `menu.${item.id}.roleIds`, suggestion: 'Keep server authorization independent from menu visibility.' });
+  }
+
+  for (const action of plan.actions) {
+    if (!has(workflowIds, action.workflowId)) addIssue(issues, { code: 'action.unknown-workflow', severity: 'error', message: `Action "${action.label}" references unknown workflow.`, path: `actions.${action.id}.workflowId` });
+    if (!action.roleIds.length) addIssue(issues, { code: 'action.missing-roles', severity: 'warning', message: `Action "${action.label}" has no role visibility contract.`, path: `actions.${action.id}.roleIds` });
+  }
+
+  const served = new Set<string>();
+  plan.surfaces.forEach(surface => surface.workflowIds.forEach(id => served.add(id)));
+  plan.menu.forEach(item => item.workflowIds.forEach(id => served.add(id)));
+  const unserved = plan.workflows.filter(workflow => !served.has(workflow.id));
+  unserved.forEach(workflow => addIssue(issues, { code: 'workflow.unserved', severity: workflow.priority === 'core' ? 'error' : 'warning', message: `Workflow "${workflow.name}" has no page or menu entry.`, path: `workflows.${workflow.id}`, suggestion: 'Add a surface or contextual entry, or mark the workflow as deferred.' }));
+
+  const roleVisibilityGaps = plan.workflows.filter(workflow => workflow.actorRoleIds.length > 0 && !plan.surfaces.some(surface => surface.workflowIds.includes(workflow.id) && (surface.roleIds.length === 0 || workflow.actorRoleIds.some(roleId => surface.roleIds.includes(roleId))))).length;
+  const orphanResourceCount = plan.resources.filter(resource => resource.workflowIds.length === 0 && !resource.internal).length;
+  const errors = issues.filter(issue => issue.severity === 'error');
+  return {
+    ok: errors.length === 0,
+    issues,
+    metrics: {
+      resourceCount: plan.resources.length,
+      workflowCount: plan.workflows.length,
+      surfaceCount: plan.surfaces.length,
+      menuNodeCount: plan.menu.length,
+      orphanResourceCount,
+      unservedWorkflowCount: unserved.length,
+      roleVisibilityGaps,
+    },
+  };
+}
+
+function reviewSurface(surface: ProductSurface, refs: { workflowIds: ReadonlySet<string>; actionIds: ReadonlySet<string>; resourceIds: ReadonlySet<string> }, issues: ProductReviewIssue[]): void {
+  if (!surface.purpose.trim()) addIssue(issues, { code: 'surface.missing-purpose', severity: 'error', message: `Surface "${surface.name}" has no purpose.`, path: `surfaces.${surface.id}.purpose` });
+  if (!surface.workflowIds.length) addIssue(issues, { code: 'surface.no-workflow', severity: 'warning', message: `Surface "${surface.name}" is not attached to a workflow.`, path: `surfaces.${surface.id}.workflowIds` });
+  surface.workflowIds.forEach(id => { if (!refs.workflowIds.has(id)) addIssue(issues, { code: 'surface.unknown-workflow', severity: 'error', message: `Surface "${surface.name}" references unknown workflow "${id}".`, path: `surfaces.${surface.id}.workflowIds` }); });
+  surface.resourceIds.forEach(id => { if (!refs.resourceIds.has(id)) addIssue(issues, { code: 'surface.unknown-resource', severity: 'error', message: `Surface "${surface.name}" references unknown resource "${id}".`, path: `surfaces.${surface.id}.resourceIds` }); });
+  surface.actionIds.forEach(id => { if (!refs.actionIds.has(id)) addIssue(issues, { code: 'surface.unknown-action', severity: 'error', message: `Surface "${surface.name}" references unknown action "${id}".`, path: `surfaces.${surface.id}.actionIds` }); });
+  if (surface.primaryActionId && !refs.actionIds.has(surface.primaryActionId)) addIssue(issues, { code: 'surface.unknown-primary-action', severity: 'error', message: `Surface "${surface.name}" references unknown primary action.`, path: `surfaces.${surface.id}.primaryActionId` });
+  if (!surface.states.length) addIssue(issues, { code: 'surface.missing-states', severity: 'warning', message: `Surface "${surface.name}" does not declare empty/loading/error/permission states.`, path: `surfaces.${surface.id}.states`, suggestion: 'Declare the states the Svelte view must implement.' });
+  if (surface.sections.length > 6) addIssue(issues, { code: 'surface.section-density', severity: 'warning', message: `Surface "${surface.name}" contains ${surface.sections.length} sections.`, path: `surfaces.${surface.id}.sections`, suggestion: 'Group related information or use progressive disclosure.' });
+  if (surface.actionIds.length > 4) addIssue(issues, { code: 'surface.action-density', severity: 'warning', message: `Surface "${surface.name}" exposes ${surface.actionIds.length} actions.`, path: `surfaces.${surface.id}.actionIds`, suggestion: 'Keep one primary action and move secondary actions into context or More.' });
+}