@auraindustry/aurajs 0.1.3 → 0.1.5

package/src/authored-project.mjs

@@ -11,6 +11,13 @@ import {
   validateStarterContentRegistries,
 } from './starter-content-registry.mjs';
 import { loadMakeCatalog } from './make-catalog.mjs';
+import { describeProjectAiGuidance, normalizeAiGuidance } from './ai-guidance.mjs';
+import {
+  PROJECT_PACKS_MANIFEST_PATH,
+  findPackOrBundleEntry,
+  listPackRegistry,
+  normalizeProjectPackManifest,
+} from './packs/catalog.mjs';
 
 export const PROJECT_REGISTRY_SCHEMA = 'aurajs.project-registry.v1';
 export const PROJECT_EXPLAIN_SCHEMA = 'aurajs.project-explain.v1';
@@ -29,6 +36,14 @@ const RUNTIME_BOOTSTRAP_FILES = [
 const SELF_WIRING_KINDS = new Set(['scene', 'ui-screen', 'prefab']);
 const CANONICAL_PREFAB_ROLE_SET = new Set(CANONICAL_PREFAB_ROLES);
 const POSIX_SEP = '/';
+const AUTHORED_SOURCE_ROOT_DIRS = Object.freeze(['src', 'scenes', 'ui', 'prefabs', 'config', 'content', 'data']);
+const STARTER_UTILS_ROOT_RELATIVE_PATH = 'src/starter-utils';
+const PROJECT_PACKS_RELATIVE_PATH = PROJECT_PACKS_MANIFEST_PATH;
+const SHARED_HELPER_PACKAGE_SPECIFIER = '@auraindustry/aurajs/helpers';
+const SUPPORTED_HELPER_PACKAGE_SPECIFIERS = Object.freeze([
+  SHARED_HELPER_PACKAGE_SPECIFIER,
+  `${SHARED_HELPER_PACKAGE_SPECIFIER}/2d`,
+]);
 
 const BASE_PROJECT_CONFIG_FILES = ['config/gameplay/game.config.json'];
 const BASE_PROJECT_CONTENT_FILES = [];
@@ -57,6 +72,7 @@ const STARTER_PROJECT_REGISTRY_PRESETS = {
     ],
     screens: [
       { id: 'hud', path: 'ui/hud.screen.js', exportName: 'default' },
+      { id: 'journal', path: 'ui/journal.screen.js', exportName: 'default' },
     ],
     prefabs: [
       { id: 'player', role: 'player', path: 'prefabs/player.prefab.js', exportName: 'default' },
@@ -64,7 +80,7 @@ const STARTER_PROJECT_REGISTRY_PRESETS = {
       { id: 'world', role: 'world', path: 'prefabs/world.prefab.js', exportName: 'default' },
     ],
     configFiles: ['config/gameplay/adventure.config.js'],
-    contentFiles: ['content/gameplay/world.js'],
+    contentFiles: ['content/gameplay/dialogue.js', 'content/gameplay/world.js', 'content/gameplay/world.tilemap.json'],
   },
   '2d-shooter': {
     startSceneId: 'gameplay',
@@ -555,6 +571,10 @@ export async function explainProject({ projectRoot, catalogRoot = null }) {
     owner: entry.owner,
     scope: entry.scope,
   }));
+  const sourceBoundary = describeSourceBoundary(projectRoot);
+  const starterUtils = describeStarterUtils(projectRoot);
+  const packs = describeProjectPacks(projectRoot);
+  const aiGuidance = describeProjectAiGuidance({ template, starterUtils });
 
   if (mode === 'bootstrap-only') {
     return {
@@ -577,6 +597,10 @@ export async function explainProject({ projectRoot, catalogRoot = null }) {
       continuity: createProjectContinuityModel(),
       starterContentRegistries,
       availableMakeKinds,
+      sourceBoundary,
+      starterUtils,
+      packs,
+      aiGuidance,
     };
   }
 
@@ -605,6 +629,10 @@ export async function explainProject({ projectRoot, catalogRoot = null }) {
     continuity: registry.continuity,
     starterContentRegistries,
     availableMakeKinds,
+    sourceBoundary,
+    starterUtils,
+    packs,
+    aiGuidance,
   };
 }
 
@@ -622,9 +650,17 @@ export async function checkProject({ projectRoot, catalogRoot = null }) {
       reasonCode: 'project_root_missing',
       errors: [{ reasonCode: 'project_root_missing', message: 'Missing aura.config.json in the current directory.' }],
       warnings,
+      sourceBoundary: null,
+      starterUtils: null,
+      aiGuidance: null,
     });
   }
 
+  const sourceBoundary = describeSourceBoundary(projectRoot);
+  const starterUtils = describeStarterUtils(projectRoot);
+  const packs = describeProjectPacks(projectRoot);
+  const aiGuidance = describeProjectAiGuidance({ template, starterUtils });
+
   if (!existsSync(registryPath)) {
     if (template === 'blank' && !hasAuthoredProjectFiles(projectRoot)) {
       return buildProjectCheckResult({
@@ -633,6 +669,10 @@ export async function checkProject({ projectRoot, catalogRoot = null }) {
         reasonCode: 'bootstrap_only_project_ok',
         errors,
         warnings,
+        sourceBoundary,
+        starterUtils,
+        packs,
+        aiGuidance,
       });
     }
     return buildProjectCheckResult({
@@ -641,6 +681,10 @@ export async function checkProject({ projectRoot, catalogRoot = null }) {
       reasonCode: 'project_registry_missing',
       errors: [{ reasonCode: 'project_registry_missing', message: 'Missing src/runtime/project-registry.js.' }],
       warnings,
+      sourceBoundary,
+      starterUtils,
+      packs,
+      aiGuidance,
     });
   }
 
@@ -658,6 +702,10 @@ export async function checkProject({ projectRoot, catalogRoot = null }) {
         path: PROJECT_REGISTRY_RELATIVE_PATH,
       }],
       warnings,
+      sourceBoundary,
+      starterUtils,
+      packs,
+      aiGuidance,
     });
   }
 
@@ -705,6 +753,10 @@ export async function checkProject({ projectRoot, catalogRoot = null }) {
     errors,
     warnings,
     starterContentRegistries: starterContentValidation.registries,
+    sourceBoundary,
+    starterUtils,
+    packs,
+    aiGuidance,
   });
 }
 
@@ -954,7 +1006,22 @@ function devRestoreOrFallback(value) {
   return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
 }
 
-function buildProjectCheckResult({ mode, ok, reasonCode, errors, warnings, starterContentRegistries = [] }) {
+function buildProjectCheckResult({
+  mode,
+  ok,
+  reasonCode,
+  errors,
+  warnings,
+  starterContentRegistries = [],
+  sourceBoundary = null,
+  starterUtils = null,
+  packs = null,
+  aiGuidance = null,
+}) {
+  const normalizedSourceBoundary = normalizeSourceBoundary(sourceBoundary);
+  const normalizedStarterUtils = normalizeStarterUtils(starterUtils);
+  const normalizedPacks = normalizeProjectPacks(packs);
+  const normalizedAiGuidance = normalizeAiGuidance(aiGuidance);
   return {
     schema: PROJECT_CHECK_SCHEMA,
     ok,
@@ -963,6 +1030,16 @@ function buildProjectCheckResult({ mode, ok, reasonCode, errors, warnings, start
     errors,
     warnings,
     starterContentRegistries,
+    sourceBoundary: normalizedSourceBoundary,
+    starterUtils: normalizedStarterUtils,
+    packs: normalizedPacks,
+    aiGuidance: normalizedAiGuidance,
+    surfaceDrift: describeProjectSurfaceDrift({
+      mode,
+      sourceBoundary: normalizedSourceBoundary,
+      starterUtils: normalizedStarterUtils,
+      aiGuidance: normalizedAiGuidance,
+    }),
   };
 }
 
@@ -998,6 +1075,43 @@ function formatExplainReport(report) {
     }
   }
 
+  lines.push('');
+  lines.push('Authoring boundary:');
+  if (!Array.isArray(report.sourceBoundary?.authoredRoots) || report.sourceBoundary.authoredRoots.length === 0) {
+    lines.push('  authored roots: (none detected)');
+  } else {
+    lines.push(`  authored roots: ${report.sourceBoundary.authoredRoots.join(', ')}`);
+  }
+  if (!Array.isArray(report.sourceBoundary?.supportedPackageImports) || report.sourceBoundary.supportedPackageImports.length === 0) {
+    lines.push('  supported shared imports: (none)');
+  } else {
+    lines.push(`  supported shared imports: ${report.sourceBoundary.supportedPackageImports.join(', ')}`);
+  }
+
+  lines.push('');
+  lines.push('Starter helper lane:');
+  if (report.starterUtils?.available !== true) {
+    lines.push('  (no scaffolded starter-utils copy detected)');
+  } else {
+    lines.push(`  root: ${report.starterUtils.rootPath}`);
+    lines.push(`  recommended import: ${report.starterUtils.recommendedImportPath || '(none)'}`);
+    lines.push(`  default package: ${report.starterUtils.defaultPackageSpecifier || SHARED_HELPER_PACKAGE_SPECIFIER}`);
+    lines.push(`  modules: ${(report.starterUtils.modules || []).map((entry) => `${entry.path} [${entry.mode}]`).join(', ') || '(none)'}`);
+  }
+
+  lines.push('');
+  lines.push('AI paved road:');
+  lines.push(`  lane: ${report.aiGuidance?.laneId || 'bootstrap-authored-project'}`);
+  if (report.aiGuidance?.summary) {
+    lines.push(`  summary: ${report.aiGuidance.summary}`);
+  }
+  lines.push(`  preferred import: ${report.aiGuidance?.recommendedImportPath || report.aiGuidance?.preferredPackageSpecifier || '(none)'}`);
+  if (!Array.isArray(report.aiGuidance?.recommendedModules) || report.aiGuidance.recommendedModules.length === 0) {
+    lines.push('  recommended modules: (none)');
+  } else {
+    lines.push(`  recommended modules: ${report.aiGuidance.recommendedModules.map((entry) => `${entry.id} -> ${entry.preferredImportSource}`).join(', ')}`);
+  }
+
   lines.push('');
   lines.push('Scenes:');
   if ((report.scenes || []).length === 0) {
@@ -1088,6 +1202,22 @@ function formatExplainReport(report) {
     }
   }
 
+  lines.push('');
+  lines.push('Optional packs:');
+  if (!Array.isArray(report.packs?.selected) || report.packs.selected.length === 0) {
+    lines.push('  (none selected)');
+  } else {
+    for (const entry of report.packs.selected) {
+      lines.push(`  ${entry.id} -> ${entry.packageName || '(unknown package)'}${entry.spec ? ` [${entry.spec}]` : ''} (${entry.sourceMode || 'package'})`);
+      if (Array.isArray(entry.vendoredPaths) && entry.vendoredPaths.length > 0) {
+        lines.push(`    vendored: ${entry.vendoredPaths.join(', ')}`);
+      }
+    }
+    for (const entry of report.packs?.bundles || []) {
+      lines.push(`  bundle ${entry.id} -> ${(entry.memberPackIds || []).join(', ') || '(none)'}`);
+    }
+  }
+
   return `${lines.join('\n')}\n`;
 }
 
@@ -1098,6 +1228,15 @@ function formatCheckReport(report) {
     `Reason code: ${report.reasonCode}`,
   ];
 
+  lines.push('');
+  lines.push(`Authoring boundary: ${(report.sourceBoundary?.authoredRoots || []).join(', ') || '(none detected)'}`);
+  lines.push(`Starter helper lane: ${report.starterUtils?.available === true ? report.starterUtils.recommendedImportPath || report.starterUtils.rootPath : '(not scaffolded)'}`);
+  lines.push(`Optional packs: ${Array.isArray(report.packs?.selected) && report.packs.selected.length > 0 ? report.packs.selected.map((entry) => entry.id).join(', ') : '(none selected)'}`);
+  lines.push(`AI paved road: ${report.aiGuidance?.laneId || 'bootstrap-authored-project'}`);
+  if (report.surfaceDrift) {
+    lines.push(`Surface status: boundary=${report.surfaceDrift.sourceBoundary.reasonCode}, helpers=${report.surfaceDrift.starterUtils.reasonCode}, lane=${report.surfaceDrift.starterLane.reasonCode}`);
+  }
+
   if ((report.errors || []).length > 0) {
     lines.push('');
     lines.push('Errors:');
@@ -1349,6 +1488,354 @@ function normalizeProjectRelativePath(value) {
   return String(value || '').split(/[/\\]+/g).filter(Boolean).join(POSIX_SEP);
 }
 
+function describeSourceBoundary(projectRoot) {
+  return {
+    authoredRoots: AUTHORED_SOURCE_ROOT_DIRS
+      .filter((relativePath) => existsSync(resolve(projectRoot, relativePath)))
+      .map((relativePath) => normalizeProjectRelativePath(relativePath)),
+    supportedPackageImports: [...SUPPORTED_HELPER_PACKAGE_SPECIFIERS],
+  };
+}
+
+function describeStarterUtils(projectRoot) {
+  const starterUtilsRoot = resolve(projectRoot, STARTER_UTILS_ROOT_RELATIVE_PATH);
+  if (!existsSync(starterUtilsRoot)) {
+    return {
+      available: false,
+      rootPath: STARTER_UTILS_ROOT_RELATIVE_PATH,
+      recommendedImportPath: null,
+      defaultPackageSpecifier: SHARED_HELPER_PACKAGE_SPECIFIER,
+      supportedPackageSpecifiers: [...SUPPORTED_HELPER_PACKAGE_SPECIFIERS],
+      modules: [],
+    };
+  }
+
+  const modules = readdirSync(starterUtilsRoot)
+    .filter((entry) => /\.(?:js|mjs)$/.test(entry))
+    .sort((left, right) => left.localeCompare(right))
+    .map((entry) => {
+      const absolutePath = resolve(starterUtilsRoot, entry);
+      const source = readFileSync(absolutePath, 'utf8');
+      const packageSpecifier = detectStarterUtilsPackageSpecifier(source);
+      return {
+        path: normalizeProjectRelativePath(`${STARTER_UTILS_ROOT_RELATIVE_PATH}/${entry}`),
+        mode: packageSpecifier ? 'package-facade' : 'authored-local',
+        packageSpecifier: packageSpecifier || null,
+        exports: listNamedExportsFromSource(source),
+      };
+    });
+
+  const indexModule = modules.find((entry) => entry.path === `${STARTER_UTILS_ROOT_RELATIVE_PATH}/index.js`) || null;
+  return {
+    available: true,
+    rootPath: STARTER_UTILS_ROOT_RELATIVE_PATH,
+    recommendedImportPath: indexModule ? './src/starter-utils/index.js' : null,
+    defaultPackageSpecifier: SHARED_HELPER_PACKAGE_SPECIFIER,
+    supportedPackageSpecifiers: [...SUPPORTED_HELPER_PACKAGE_SPECIFIERS],
+    modules,
+  };
+}
+
+function describeProjectPacks(projectRoot) {
+  const manifestPath = resolve(projectRoot, PROJECT_PACKS_RELATIVE_PATH);
+  const packageJsonPath = resolve(projectRoot, 'package.json');
+  const packageJson = existsSync(packageJsonPath)
+    ? JSON.parse(readFileSync(packageJsonPath, 'utf8'))
+    : {};
+  const dependencies = packageJson.dependencies && typeof packageJson.dependencies === 'object'
+    ? packageJson.dependencies
+    : {};
+  const manifest = existsSync(manifestPath)
+    ? normalizeProjectPackManifest(JSON.parse(readFileSync(manifestPath, 'utf8')))
+    : normalizeProjectPackManifest(null);
+
+  const selectedPacks = manifest.packs.length > 0
+    ? manifest.packs.map((entry) => {
+      const catalog = findPackOrBundleEntry(entry.id);
+      return {
+        id: entry.id,
+        kind: entry.kind,
+        packageName: entry.packageName || catalog?.packageName || null,
+        spec: entry.spec || (entry.packageName && typeof dependencies[entry.packageName] === 'string' ? dependencies[entry.packageName] : null),
+        installMode: entry.installMode === 'workspace' ? 'workspace' : 'package',
+        sourceMode: entry.sourceMode === 'github'
+          ? 'github'
+          : entry.sourceMode === 'workspace'
+            ? 'workspace'
+            : 'package',
+        vendoredPaths: Array.isArray(entry.vendoredPaths) ? entry.vendoredPaths.map((item) => String(item)) : [],
+        title: catalog?.title || null,
+      };
+    })
+    : listPackRegistry()
+      .filter((entry) => typeof dependencies[entry.packageName] === 'string')
+      .map((entry) => ({
+        id: entry.id,
+        kind: entry.kind,
+        packageName: entry.packageName,
+        spec: dependencies[entry.packageName],
+        installMode: String(dependencies[entry.packageName]).startsWith('file:') ? 'workspace' : 'package',
+        sourceMode: String(dependencies[entry.packageName]).startsWith('file:') ? 'workspace' : 'package',
+        vendoredPaths: [],
+        title: entry.title,
+      }));
+
+  return {
+    available: selectedPacks.length > 0 || manifest.bundles.length > 0 || existsSync(manifestPath),
+    manifestPath: existsSync(manifestPath) ? PROJECT_PACKS_RELATIVE_PATH : null,
+    selected: selectedPacks,
+    bundles: manifest.bundles.map((entry) => {
+      const catalog = findPackOrBundleEntry(entry.id);
+      return {
+        id: entry.id,
+        packageName: entry.packageName || catalog?.packageName || null,
+        memberPackIds: Array.isArray(entry.memberPackIds) ? entry.memberPackIds.map((item) => String(item)) : [],
+        github: catalog?.github ? { ...catalog.github } : null,
+        title: catalog?.title || null,
+      };
+    }),
+  };
+}
+
+function detectStarterUtilsPackageSpecifier(source) {
+  const match = String(source || '').match(/from ['"](@auraindustry\/aurajs\/helpers(?:\/2d)?)['"]/);
+  return match ? match[1] : null;
+}
+
+function listNamedExportsFromSource(source) {
+  const names = [];
+  const seen = new Set();
+  const lines = String(source || '').split(/\r?\n/);
+
+  const pushName = (value) => {
+    if (!value || seen.has(value)) {
+      return;
+    }
+    seen.add(value);
+    names.push(value);
+  };
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const trimmed = lines[index].trim();
+    if (!trimmed.startsWith('export ')) {
+      continue;
+    }
+
+    const functionExport = trimmed.match(/^export\s+function\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*\(/);
+    if (functionExport) {
+      pushName(functionExport[1]);
+      continue;
+    }
+
+    const classExport = trimmed.match(/^export\s+class\s+([A-Za-z_$][A-Za-z0-9_$]*)\b/);
+    if (classExport) {
+      pushName(classExport[1]);
+      continue;
+    }
+
+    const variableExport = trimmed.match(/^export\s+(?:const|let|var)\s+([A-Za-z_$][A-Za-z0-9_$]*)\b/);
+    if (variableExport) {
+      pushName(variableExport[1]);
+      continue;
+    }
+
+    if (trimmed.startsWith('export {')) {
+      let statement = trimmed;
+      while (!statement.includes('}') && index + 1 < lines.length) {
+        index += 1;
+        statement += ` ${lines[index].trim()}`;
+      }
+      const match = statement.match(/^export\s*\{([^}]+)\}/);
+      if (!match) {
+        continue;
+      }
+      for (const entry of match[1].split(',')) {
+        const spec = entry.trim();
+        if (!spec) continue;
+        const alias = spec.match(/^([A-Za-z_$][A-Za-z0-9_$]*)\s+as\s+([A-Za-z_$][A-Za-z0-9_$]*)$/);
+        pushName(alias ? alias[2] : spec);
+      }
+    }
+  }
+
+  return names;
+}
+
+function normalizeSourceBoundary(boundary) {
+  const safe = boundary && typeof boundary === 'object' && !Array.isArray(boundary) ? boundary : {};
+  return {
+    authoredRoots: Array.isArray(safe.authoredRoots) ? safe.authoredRoots.map((entry) => normalizeProjectRelativePath(entry)) : [],
+    supportedPackageImports: Array.isArray(safe.supportedPackageImports) ? safe.supportedPackageImports.map((entry) => String(entry)) : [],
+  };
+}
+
+function normalizeStarterUtils(starterUtils) {
+  const safe = starterUtils && typeof starterUtils === 'object' && !Array.isArray(starterUtils) ? starterUtils : {};
+  return {
+    available: safe.available === true,
+    rootPath: safe.rootPath ? normalizeProjectRelativePath(safe.rootPath) : STARTER_UTILS_ROOT_RELATIVE_PATH,
+    recommendedImportPath: typeof safe.recommendedImportPath === 'string' && safe.recommendedImportPath.trim().length > 0
+      ? safe.recommendedImportPath.trim()
+      : null,
+    defaultPackageSpecifier: typeof safe.defaultPackageSpecifier === 'string' && safe.defaultPackageSpecifier.trim().length > 0
+      ? safe.defaultPackageSpecifier.trim()
+      : SHARED_HELPER_PACKAGE_SPECIFIER,
+    supportedPackageSpecifiers: Array.isArray(safe.supportedPackageSpecifiers)
+      ? safe.supportedPackageSpecifiers.map((entry) => String(entry))
+      : [...SUPPORTED_HELPER_PACKAGE_SPECIFIERS],
+    modules: Array.isArray(safe.modules)
+      ? safe.modules.map((entry) => ({
+        path: normalizeProjectRelativePath(entry.path),
+        mode: entry.mode === 'authored-local' ? 'authored-local' : 'package-facade',
+        packageSpecifier: typeof entry.packageSpecifier === 'string' && entry.packageSpecifier.trim().length > 0
+          ? entry.packageSpecifier.trim()
+          : null,
+        exports: Array.isArray(entry.exports) ? entry.exports.map((name) => String(name)) : [],
+      }))
+      : [],
+  };
+}
+
+function normalizeProjectPacks(packs) {
+  const safe = packs && typeof packs === 'object' && !Array.isArray(packs) ? packs : {};
+  return {
+    available: safe.available === true,
+    manifestPath: typeof safe.manifestPath === 'string' && safe.manifestPath.trim().length > 0
+      ? normalizeProjectRelativePath(safe.manifestPath)
+      : null,
+    selected: Array.isArray(safe.selected)
+      ? safe.selected.map((entry) => ({
+        id: typeof entry.id === 'string' ? entry.id : null,
+        kind: typeof entry.kind === 'string' ? entry.kind : 'starter-pack',
+        packageName: typeof entry.packageName === 'string' ? entry.packageName : null,
+        spec: typeof entry.spec === 'string' ? entry.spec : null,
+        installMode: entry.installMode === 'workspace' ? 'workspace' : 'package',
+        sourceMode: entry.sourceMode === 'github'
+          ? 'github'
+          : entry.sourceMode === 'workspace'
+            ? 'workspace'
+            : 'package',
+        vendoredPaths: Array.isArray(entry.vendoredPaths) ? entry.vendoredPaths.map((item) => String(item)) : [],
+        title: typeof entry.title === 'string' ? entry.title : null,
+      })).filter((entry) => entry.id)
+      : [],
+    bundles: Array.isArray(safe.bundles)
+      ? safe.bundles.map((entry) => ({
+        id: typeof entry.id === 'string' ? entry.id : null,
+        packageName: typeof entry.packageName === 'string' ? entry.packageName : null,
+        memberPackIds: Array.isArray(entry.memberPackIds) ? entry.memberPackIds.map((item) => String(item)) : [],
+        github: entry.github && typeof entry.github === 'object' && !Array.isArray(entry.github)
+          ? {
+            repository: typeof entry.github.repository === 'string' ? entry.github.repository : null,
+            ref: typeof entry.github.ref === 'string' ? entry.github.ref : null,
+          }
+          : null,
+        title: typeof entry.title === 'string' ? entry.title : null,
+      })).filter((entry) => entry.id)
+      : [],
+  };
+}
+
+function normalizeSurfaceDrift(value) {
+  const safe = value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+  const normalizeEntry = (entry, fallbackReasonCode) => {
+    const source = entry && typeof entry === 'object' && !Array.isArray(entry) ? entry : {};
+    return {
+      status: typeof source.status === 'string' && source.status.trim().length > 0
+        ? source.status.trim()
+        : 'info',
+      reasonCode: typeof source.reasonCode === 'string' && source.reasonCode.trim().length > 0
+        ? source.reasonCode.trim()
+        : fallbackReasonCode,
+      message: typeof source.message === 'string' && source.message.trim().length > 0
+        ? source.message.trim()
+        : null,
+    };
+  };
+
+  return {
+    sourceBoundary: normalizeEntry(safe.sourceBoundary, 'source_boundary_unknown'),
+    starterUtils: normalizeEntry(safe.starterUtils, 'starter_utils_unknown'),
+    starterLane: normalizeEntry(safe.starterLane, 'starter_lane_unknown'),
+  };
+}
+
+function describeProjectSurfaceDrift({ mode, sourceBoundary, starterUtils, aiGuidance }) {
+  const authoredRoots = Array.isArray(sourceBoundary?.authoredRoots) ? sourceBoundary.authoredRoots : [];
+  const hasStarterUtils = starterUtils?.available === true;
+  const hasStarterImport = typeof starterUtils?.recommendedImportPath === 'string' && starterUtils.recommendedImportPath.trim().length > 0;
+  const laneId = typeof aiGuidance?.laneId === 'string' && aiGuidance.laneId.trim().length > 0
+    ? aiGuidance.laneId.trim()
+    : 'bootstrap-authored-project';
+  const preferredPackageSpecifier = typeof aiGuidance?.preferredPackageSpecifier === 'string' && aiGuidance.preferredPackageSpecifier.trim().length > 0
+    ? aiGuidance.preferredPackageSpecifier.trim()
+    : null;
+
+  const sourceBoundaryStatus = authoredRoots.length > 0
+    ? {
+        status: 'pass',
+        reasonCode: 'source_boundary_detected',
+        message: `Authored roots detected: ${authoredRoots.join(', ')}.`,
+      }
+    : {
+        status: 'warn',
+        reasonCode: 'source_boundary_empty',
+        message: 'No authored roots were detected under the canonical project surface.',
+      };
+
+  let starterUtilsStatus = {
+    status: 'info',
+    reasonCode: 'starter_utils_not_scaffolded',
+    message: 'No local starter-utils lane is present in this project.',
+  };
+  if (hasStarterUtils && hasStarterImport) {
+    starterUtilsStatus = {
+      status: 'pass',
+      reasonCode: 'starter_utils_detected',
+      message: `Starter helper lane is available at ${starterUtils.recommendedImportPath}.`,
+    };
+  } else if (hasStarterUtils) {
+    starterUtilsStatus = {
+      status: 'warn',
+      reasonCode: 'starter_utils_entry_missing',
+      message: 'Starter helper files exist, but src/starter-utils/index.js is missing.',
+    };
+  }
+
+  let starterLaneStatus = {
+    status: 'info',
+    reasonCode: 'starter_lane_bootstrap',
+    message: 'This project is currently on the bootstrap-authored lane.',
+  };
+  if (mode === 'registry' && laneId !== 'bootstrap-authored-project') {
+    if (hasStarterUtils && hasStarterImport) {
+      starterLaneStatus = {
+        status: 'pass',
+        reasonCode: 'starter_lane_local_helpers',
+        message: `AI paved road ${laneId} is aligned with local starter-utils imports.`,
+      };
+    } else if (preferredPackageSpecifier) {
+      starterLaneStatus = {
+        status: 'info',
+        reasonCode: 'starter_lane_package_surface',
+        message: `AI paved road ${laneId} currently resolves through ${preferredPackageSpecifier}.`,
+      };
+    } else {
+      starterLaneStatus = {
+        status: 'warn',
+        reasonCode: 'starter_lane_unresolved',
+        message: `AI paved road ${laneId} does not have a local helper lane or preferred package surface.`,
+      };
+    }
+  }
+
+  return {
+    sourceBoundary: sourceBoundaryStatus,
+    starterUtils: starterUtilsStatus,
+    starterLane: starterLaneStatus,
+  };
+}
+
 function toImportPath(relativePath) {
   const normalized = normalizeProjectRelativePath(relativePath);
   if (normalized.startsWith('.')) return normalized;
@@ -1420,6 +1907,10 @@ function normalizeExplainPayload(explained) {
         scope: entry.scope || 'core',
       }))
       : [],
+    sourceBoundary: normalizeSourceBoundary(explained.sourceBoundary),
+    starterUtils: normalizeStarterUtils(explained.starterUtils),
+    packs: normalizeProjectPacks(explained.packs),
+    aiGuidance: normalizeAiGuidance(explained.aiGuidance),
   };
 }
 
@@ -1433,6 +1924,11 @@ function normalizeCheckPayload({ projectRoot, checked }) {
     errors: Array.isArray(checked.errors) ? checked.errors : [],
     warnings: Array.isArray(checked.warnings) ? checked.warnings : [],
     starterContentRegistries: Array.isArray(checked.starterContentRegistries) ? checked.starterContentRegistries : [],
+    sourceBoundary: normalizeSourceBoundary(checked.sourceBoundary),
+    starterUtils: normalizeStarterUtils(checked.starterUtils),
+    packs: normalizeProjectPacks(checked.packs),
+    aiGuidance: normalizeAiGuidance(checked.aiGuidance),
+    surfaceDrift: normalizeSurfaceDrift(checked.surfaceDrift),
   };
 }