pi-apexlang 0.2.2 → 0.4.0

package/skills/apexlang/tools/apexctl.mjs

@@ -40,6 +40,23 @@ function readOption(args, name, fallback = "") {
   return args[index + 1];
 }
 
+function readPositiveIntegerOption(args, name, fallback) {
+  const index = args.indexOf(name);
+  const rawValue = index === -1 ? String(fallback) : args[index + 1];
+  if (typeof rawValue !== "string" || !/^[1-9]\d*$/.test(rawValue)) {
+    throw new Error(`${name} must be a positive integer`);
+  }
+  const value = Number(rawValue);
+  if (!Number.isSafeInteger(value)) {
+    throw new Error(`${name} must be a positive integer`);
+  }
+  return value;
+}
+
+function readOptions(args, name) {
+  return args.flatMap((value, index) => value === name && index + 1 < args.length ? [args[index + 1]] : []);
+}
+
 function isPathInside(rootPath, targetPath) {
   const relative = path.relative(path.resolve(rootPath), path.resolve(targetPath));
   return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
@@ -150,9 +167,14 @@ function printUsage() {
   node tools/apexctl.mjs runtime verify-ui --app-path <path> [--runtime-base-url <url>] [--runtime-page-url <url>] [--runtime-provider <auto|chrome-devtools-mcp|http-fallback>] [--page <id>] [--artifact-dir <path>] [--report-path <path>]
   node tools/apexctl.mjs runtime validate --app-path <absolute_path> --db-connection-name <name> [--apex-root <path>] [--compiler-oracle-home <path>] [--execution-mode <auto|build-root|path>] [--workspaceid <id>] [--artifact-dir <path>] [--vscode-problems-path <path>] [--report-path <path>] [--transcript-path <path>]
   node tools/apexctl.mjs runtime roundtrip --app-path <path> --db-connection-name <name> [--import-intent <validate-only|validate-and-import>] [--execution-mode <auto|build-root|path>] [--target-resolution-mode <update-existing|create-new>] [--create-new-confirmed] [--workspaceid <id>] [--runtime-base-url <url>] [--runtime-page-url <url>] [--runtime-provider <auto|chrome-devtools-mcp|http-fallback>] [--page <id>] [--artifact-dir <path>] [--require-runtime-verification] [--skip-runtime-verification] [--supporting-objects] [--preflight-only] [--import-mode <auto|direct>] [--apex-root <path>] [--report-path <path>] [--transcript-path <path>]
-  node tools/apexctl.mjs runtime predeploy --app-path <path> [--fix-vocab]
+  node tools/apexctl.mjs runtime predeploy --app-path <path> [--fix-vocab] [--generation-plan <path>] [--require-smart-filter-generation-plan]
+  node tools/apexctl.mjs apexlang format --app-path <path> [--strict-structure]
   node tools/apexctl.mjs apexlang validate --app-path <path> [--fix-vocab]
+  node tools/apexctl.mjs apexlang grammar contract --components <name[,name...]> [--children <parent.child[,parent.child...]>] [--instance <parent.child[id].[group.]property=value>]... [--groups <name[,name...]>] [--when <component[.group].property=value>]... [--compiler-oracle-home <path>] [--cache-dir <path>] [--no-cache]
+  node tools/apexctl.mjs apexlang grammar audit --artifact-path <path> --components <name[,name...]> [--children <parent.child[,parent.child...]>] [--instance <parent.child[id].[group.]property=value>]... [--groups <name[,name...]>] [--when <component[.group].property=value>]... [--compiler-oracle-home <path>] [--cache-dir <path>] [--no-cache]
   node tools/apexctl.mjs apexlang compiler-truth audit --app-path <path> [--report-path <path>] [--compiler-oracle-home <path>] [--verify-component-attributes]
+  node tools/apexctl.mjs context resolve --intent <text> [--phase <draft|critique|revision>] [--max-bytes <count>] [--cache-path <path>] [--no-cache] [--require-ready]
+  node tools/apexctl.mjs context repair [--problems <path>] [--rule-id <id[,id...]>] [--unit-id <id>] [--ir-pointer <pointer>] [--cache-path <path>] [--no-cache]
   node tools/apexctl.mjs diagnostics resolve-build-root --db-connection-name <name> [--apex-root <path>] [--report-path <path>]
 `);
 }
@@ -275,7 +297,12 @@ async function materializeNewApp(packageRoot, appPath, workspaceNameInput) {
   return 0;
 }
 
-async function runApexlangValidation(packageRoot, runtimeRoot, appPath, { fixVocab = false } = {}) {
+async function runApexlangValidation(
+  packageRoot,
+  runtimeRoot,
+  appPath,
+  { fixVocab = false, generationPlan = "", requireSmartFilterGenerationPlan = false } = {}
+) {
   if (!appPath) {
     console.error("Missing required --app-path");
     return 1;
@@ -301,6 +328,8 @@ async function runApexlangValidation(packageRoot, runtimeRoot, appPath, { fixVoc
         path.join(runtimeRoot, "internal", "python", "validate_apexlang.py"),
         "--report-path",
         path.join(reportDir, "apexlang-dsl-report.json"),
+        ...(generationPlan ? ["--generation-plan", generationPlan] : []),
+        ...(requireSmartFilterGenerationPlan ? ["--require-smart-filter-generation-plan"] : []),
         appPath
       ]
     ],
@@ -340,6 +369,25 @@ async function runApexlangValidation(packageRoot, runtimeRoot, appPath, { fixVoc
   return 0;
 }
 
+async function runApexlangFormat(runtimeRoot, appPath, strictStructure = false) {
+  if (!appPath) {
+    console.error("Missing required --app-path");
+    return 1;
+  }
+  const reportDir = path.join(process.env.APEXLANG_OUTPUT_ROOT, "logs");
+  await ensureDir(reportDir);
+  const result = spawnSync("python3", [
+    path.join(runtimeRoot, "internal", "python", "format_apexlang.py"),
+    appPath,
+    "--report-path",
+    path.join(reportDir, "apexlang-format-report.json"),
+    ...(strictStructure ? ["--strict-structure"] : [])
+  ], { cwd: process.cwd(), encoding: "utf8", env: process.env });
+  if (result.stdout) process.stdout.write(result.stdout);
+  if (result.stderr) process.stderr.write(result.stderr);
+  return typeof result.status === "number" ? result.status : 1;
+}
+
 async function handleWorkspace(runtimeModule, args) {
   const intelligencePath = path.join(process.cwd(), "assets", "workspace-intelligence.json");
   const intelligence = (await readJsonIfPresent(intelligencePath)) ?? runtimeModule.DEFAULT_CONFIG;
@@ -457,8 +505,61 @@ async function handleDiagnostics(runtimeModule, args) {
   return result.code;
 }
 
+async function writeContextCapsule(runRoot, result, args, kind) {
+  if (parseFlag(args, "--no-cache")) {
+    return "";
+  }
+  const requestedPath = readOption(args, "--cache-path", "");
+  const cachePath = requestedPath
+    ? path.resolve(requestedPath)
+    : path.join(runRoot, "context-capsules", kind + "-" + result.fingerprint + ".json");
+  await ensureDir(path.dirname(cachePath));
+  await writeJson(cachePath, result.payload);
+  return cachePath;
+}
+
+async function handleContext(runRoot, args) {
+  const action = args[0];
+  try {
+    const { resolveContextCapsule, resolveRepairCapsule } = await import("../runtime/lib/catalogs.mjs");
+    if (action === "resolve") {
+      const maxBytes = readPositiveIntegerOption(args, "--max-bytes", 12000);
+      const result = await resolveContextCapsule({
+        intent: readOption(args, "--intent", ""),
+        phase: readOption(args, "--phase", "draft"),
+        maxBytes
+      });
+      const cachePath = await writeContextCapsule(runRoot, result, args, "context");
+      console.log(JSON.stringify({ ...result.payload, capsule_bytes: result.bytes, cache_path: cachePath }, null, 2));
+      if (parseFlag(args, "--require-ready") && result.payload.generation_status !== "ready") {
+        console.error("APEXLANG_CONTEXT_BLOCKED " + result.payload.routing_decision.missingInputs.join(","));
+        return 2;
+      }
+      return 0;
+    }
+    if (action === "repair") {
+      const problemsPath = readOption(args, "--problems", "");
+      const problems = problemsPath ? await readJson(path.resolve(problemsPath)) : null;
+      const result = await resolveRepairCapsule({
+        ruleIds: args.flatMap((value, index) => value === "--rule-id" && args[index + 1] ? [args[index + 1]] : []),
+        problems,
+        unitId: readOption(args, "--unit-id", ""),
+        irPointer: readOption(args, "--ir-pointer", "")
+      });
+      const cachePath = await writeContextCapsule(runRoot, result, args, "repair");
+      console.log(JSON.stringify({ ...result.payload, capsule_bytes: result.bytes, cache_path: cachePath }, null, 2));
+      return 0;
+    }
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    return 1;
+  }
+  printUsage();
+  return 1;
+}
+
 async function main() {
-  const { packageRoot, runtimeRoot, runtimeModule } = await prepareRuntimeEnvironment();
+  const { packageRoot, runtimeRoot, runRoot, runtimeModule } = await prepareRuntimeEnvironment();
   const args = process.argv.slice(2);
   const namespace = args[0];
   const rest = args.slice(1);
@@ -473,11 +574,70 @@ async function main() {
   if (namespace === "new-app" && rest[0] === "materialize") {
     return materializeNewApp(packageRoot, readOption(rest, "--app-path", ""), readOption(rest, "--workspace-name", ""));
   }
+  if (namespace === "apexlang" && rest[0] === "format") {
+    return runApexlangFormat(runtimeRoot, readOption(rest, "--app-path", ""), parseFlag(rest, "--strict-structure"));
+  }
   if (namespace === "apexlang" && rest[0] === "validate") {
     return runApexlangValidation(packageRoot, runtimeRoot, readOption(rest, "--app-path", ""), {
-      fixVocab: parseFlag(rest, "--fix-vocab")
+      fixVocab: parseFlag(rest, "--fix-vocab"),
+      generationPlan: readOption(rest, "--generation-plan", ""),
+      requireSmartFilterGenerationPlan: parseFlag(rest, "--require-smart-filter-generation-plan")
     });
   }
+  if (namespace === "apexlang" && rest[0] === "grammar" && rest[1] === "contract") {
+    const components = readOption(rest, "--components", "");
+    if (!components.trim()) {
+      console.error("Missing required --components");
+      return 1;
+    }
+    const { buildGrammarContract } = await import(pathToFileURL(path.join(runtimeRoot, "grammar_contract.mjs")).href);
+    try {
+      const result = await buildGrammarContract({
+        components: [components],
+        children: [readOption(rest, "--children", "")],
+        instances: readOptions(rest, "--instance"),
+        groups: [readOption(rest, "--groups", "")],
+        conditions: readOptions(rest, "--when"),
+        compilerOracleHome: readOption(rest, "--compiler-oracle-home", readOption(rest, "--oracle-home", "")),
+        cacheDir: readOption(rest, "--cache-dir", ""),
+        useCache: !parseFlag(rest, "--no-cache"),
+        compilerOracleHome: readOption(rest, "--compiler-oracle-home", readOption(rest, "--oracle-home", ""))
+      });
+      console.log(JSON.stringify({ ...result.contract, cache: { status: result.cacheStatus, path: result.cachePath } }, null, 2));
+      return 0;
+    } catch (error) {
+      console.error(`APEXLANG_GRAMMAR_CONTRACT_FAILED ${error.message}`);
+      return 1;
+    }
+  }
+  if (namespace === "apexlang" && rest[0] === "grammar" && rest[1] === "audit") {
+    const components = readOption(rest, "--components", "");
+    const artifactPath = readOption(rest, "--artifact-path", "");
+    if (!components.trim() || !artifactPath.trim()) {
+      console.error("Missing required --components or --artifact-path");
+      return 1;
+    }
+    const { auditGrammarContract, buildGrammarContract } = await import(pathToFileURL(path.join(runtimeRoot, "grammar_contract.mjs")).href);
+    try {
+      const { contract } = await buildGrammarContract({
+        components: [components],
+        children: [readOption(rest, "--children", "")],
+        instances: readOptions(rest, "--instance"),
+        groups: [readOption(rest, "--groups", "")],
+        conditions: readOptions(rest, "--when"),
+        compilerOracleHome: readOption(rest, "--compiler-oracle-home", readOption(rest, "--oracle-home", "")),
+        cacheDir: readOption(rest, "--cache-dir", ""),
+        useCache: !parseFlag(rest, "--no-cache"),
+        compilerOracleHome: readOption(rest, "--compiler-oracle-home", readOption(rest, "--oracle-home", ""))
+      });
+      const audit = await auditGrammarContract({ contract, artifactPath });
+      console.log(JSON.stringify(audit, null, 2));
+      return audit.status === "passed" ? 0 : 1;
+    } catch (error) {
+      console.error(`APEXLANG_GRAMMAR_AUDIT_FAILED ${error.message}`);
+      return 1;
+    }
+  }
   if (namespace === "apexlang" && rest[0] === "compiler-truth" && rest[1] === "audit") {
     const auditToolPath = path.join(packageRoot, "tools", "compiler-truth-audit.mjs");
     const result = spawnSync("node", [
@@ -504,6 +664,9 @@ async function main() {
   if (namespace === "runtime") {
     return handleRuntime(packageRoot, runtimeModule, rest);
   }
+  if (namespace === "context") {
+    return handleContext(runRoot, rest);
+  }
   if (namespace === "diagnostics") {
     return handleDiagnostics(runtimeModule, rest);
   }

package/skills/apexlang/tools/compiler-truth-audit.mjs

@@ -3,8 +3,12 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { buildOracleNormalizedMap, ORACLE_NORMALIZER_VERSION, readOracleRuntimeMetadata } from "./query-valid-props-normalize.mjs";
-import { resolveOracleRuntime } from "./query-valid-props-runtime.mjs";
+import { loadOracleCompilerContext } from "./query-valid-props-context.mjs";
+import {
+  normalizeSemanticValue,
+  resolveAuditComponentRecord as resolveRecordFor,
+  resolveAuditProperty
+} from "./query-valid-props-semantics.mjs";
 
 const SCRIPT_PATH = fileURLToPath(import.meta.url);
 const IS_PACKAGED_ROOT = path.basename(path.dirname(SCRIPT_PATH)) === "tools";
@@ -29,14 +33,11 @@ const SUPPORTED_COMPONENTS = new Set([
   "process",
   "computation",
   "validation",
+  "lov",
   "list",
   "entry",
   "breadcrumb",
 ]);
-const COMPILER_METADATA_PROPERTY_ALIASES = new Map([
-  ["app.authentication.scheme", "authenticationScheme"]
-]);
-
 function defaultCommand() {
   return IS_PACKAGED_ROOT
     ? "node tools/compiler-truth-audit.mjs"
@@ -153,38 +154,21 @@ async function collectApxFiles(targetPath) {
   return files.sort();
 }
 
-function buildCompilerContext(oracleHome) {
-  const oracleRuntime = resolveOracleRuntime(oracleHome || undefined);
-  const { metadata, buildId, metadataHash } = readOracleRuntimeMetadata(oracleRuntime.compilerJarPath);
-  const map = buildOracleNormalizedMap({
-    metadata,
-    compilerJarPath: oracleRuntime.compilerJarPath,
-    oracleHome: oracleRuntime.oracleHome,
-    source: oracleRuntime.source
-  });
-  const provenance = {
-    buildID: buildId,
-    metadataHash,
-    normalizerVersion: ORACLE_NORMALIZER_VERSION,
-    source: oracleRuntime.source,
-    oracleHome: oracleRuntime.oracleHome,
-    compilerJar: oracleRuntime.compilerJarPath
-  };
-  return { map, provenance };
-}
-
-function firstRecordFor(map, singular, parentSingular = "") {
-  const records = map.componentTypes.filter((record) => record.singular === singular);
-  if (!records.length) {
-    return null;
-  }
-  if (parentSingular) {
-    const parentMatch = records.find((record) => record.parentComponentType === parentSingular);
-    if (parentMatch) {
-      return parentMatch;
-    }
+function normalizePropertySemanticValue(property, value) {
+  const normalized = normalizeSemanticValue(value);
+  if (
+    property?.propertyId === "94" &&
+    property?.lov?.type === "PLUGINS" &&
+    String(normalized).startsWith("themeTemplateComponent/")
+  ) {
+    const pluginName = String(normalized).slice("themeTemplateComponent/".length);
+    return `TMPL_${pluginName}`;
   }
-  return records.length === 1 ? records[0] : records[0];
+  const token = String(normalized).replace(/[^A-Za-z0-9]/g, "").toLowerCase();
+  const match = (property?.lov?.values || []).find(({ name, returnValue }) =>
+    [name, returnValue].some((candidate) =>
+      String(candidate ?? "").replace(/[^A-Za-z0-9]/g, "").toLowerCase() === token));
+  return match?.returnValue || normalized;
 }
 
 function nearestComponent(stack) {
@@ -255,26 +239,18 @@ function addIssue(issues, filePath, lineNumber, code, message, details = {}) {
   });
 }
 
-function compilerMetadataPropertyNames(componentName, groupName, propertyName) {
-  const names = [propertyName];
-  const scopedKey = groupName
-    ? `${componentName}.${groupName}.${propertyName}`
-    : `${componentName}.${propertyName}`;
-  const alias = COMPILER_METADATA_PROPERTY_ALIASES.get(scopedKey);
-  if (alias && !names.includes(alias)) {
-    names.push(alias);
-  }
-  return names;
-}
-
 function validateProperty({ issues, filePath, lineNumber, componentFrame, groupFrame, propertyName }) {
   if (!componentFrame?.record || !propertyName) {
-    return;
+    return null;
   }
-  const compilerPropertyNames = compilerMetadataPropertyNames(componentFrame.name, groupFrame?.name || "", propertyName);
+  const { property: match, conditionState } = resolveAuditProperty({
+    record: componentFrame.record,
+    componentName: componentFrame.name,
+    groupName: groupFrame?.name || "",
+    propertyName,
+    props: componentFrame.props || {}
+  });
   if (groupFrame) {
-    const props = componentFrame.record.groups[groupFrame.name] || [];
-    const match = props.find((prop) => compilerPropertyNames.includes(prop.propertyName));
     if (!match) {
       addIssue(
         issues,
@@ -289,12 +265,27 @@ function validateProperty({ issues, filePath, lineNumber, componentFrame, groupF
           property: propertyName
         }
       );
+      return null;
     }
-    return;
+    if (conditionState === "false") {
+      addIssue(
+        issues,
+        filePath,
+        lineNumber,
+        "COMPILER_TRUTH_PROP_INACTIVE",
+        `${componentFrame.name}.${groupFrame.name}.${propertyName} exists in compiler metadata but is inactive under current component assumptions`,
+        {
+          component: componentFrame.name,
+          componentTypeId: componentFrame.record.componentTypeId,
+          group: groupFrame.name,
+          property: propertyName
+        }
+      );
+    }
+    return match;
   }
 
-  const anyMatch = componentFrame.record.properties.some((prop) => compilerPropertyNames.includes(prop.propertyName));
-  if (!anyMatch) {
+  if (!match) {
     addIssue(
       issues,
       filePath,
@@ -307,7 +298,23 @@ function validateProperty({ issues, filePath, lineNumber, componentFrame, groupF
         property: propertyName
       }
     );
+    return null;
+  }
+  if (conditionState === "false") {
+    addIssue(
+      issues,
+      filePath,
+      lineNumber,
+      "COMPILER_TRUTH_PROP_INACTIVE",
+      `${componentFrame.name}.${propertyName} exists in compiler metadata but is inactive under current component assumptions`,
+      {
+        component: componentFrame.name,
+        componentTypeId: componentFrame.record.componentTypeId,
+        property: propertyName
+      }
+    );
   }
+  return match;
 }
 
 export function auditApxText(filePath, text, map) {
@@ -326,9 +333,9 @@ export function auditApxText(filePath, text, map) {
     const currentComponent = nearestComponent(stack);
     const currentGroup = nearestGroup(stack);
     const opaqueScope = insideOpaque(stack);
-    const propMatch = trimmed.match(/^([A-Za-z][A-Za-z0-9]*)\s*:/);
+    const propMatch = trimmed.match(/^([A-Za-z][A-Za-z0-9]*)\s*:\s*(.*)$/);
     if (propMatch && currentComponent && !opaqueScope) {
-      validateProperty({
+      const compilerProperty = validateProperty({
         issues,
         filePath,
         lineNumber,
@@ -336,9 +343,17 @@ export function auditApxText(filePath, text, map) {
         groupFrame: currentGroup,
         propertyName: propMatch[1]
       });
+      currentComponent.props ||= {};
+      const semanticValue = normalizePropertySemanticValue(compilerProperty, propMatch[2]);
+      if (currentComponent.props[propMatch[1]] === undefined) {
+        currentComponent.props[propMatch[1]] = semanticValue;
+      }
+      if (compilerProperty?.propertyId) {
+        currentComponent.props[String(compilerProperty.propertyId)] = semanticValue;
+      }
     }
 
-    const blockMatch = trimmed.match(/^([A-Za-z][A-Za-z0-9]*)\b(?:\s+[^({]+?)?\s*([({])/);
+    const blockMatch = trimmed.match(/^([A-Za-z][A-Za-z0-9]*(?:-[A-Za-z][A-Za-z0-9]*)*)\b(?:\s+[^({]+?)?\s*([({])/);
     if (blockMatch) {
       const [, token, delimiter] = blockMatch;
       const parentComponent = nearestComponent(stack);
@@ -346,8 +361,25 @@ export function auditApxText(filePath, text, map) {
       const { opens, closes } = lineOpenCloseBalance(line);
       const shouldPush = opens > closes;
       if (delimiter === "(" && SUPPORTED_COMPONENTS.has(token)) {
-        const record = firstRecordFor(map, token, parentName);
-        if (record) {
+        const { record, failure, candidates } = resolveRecordFor(map, token, parentComponent);
+        if (!record) {
+          addIssue(
+            issues,
+            filePath,
+            lineNumber,
+            failure === "ambiguous" ? "COMPILER_TRUTH_COMPONENT_AMBIGUOUS" : "COMPILER_TRUTH_COMPONENT_UNKNOWN",
+            failure === "ambiguous"
+              ? `${token} resolves to multiple compiler component records; add parent/type context (${(candidates || []).map((record) => record.componentTypeId).join(", ")})`
+              : `${token} is not valid under parent ${parentName || "none"} for current compiler metadata assumptions`,
+            {
+              component: token,
+              parent: parentName || ""
+            }
+          );
+          if (shouldPush) {
+            stack.push({ kind: "component", name: token, record: null, props: {} });
+          }
+        } else {
           observations.push({
             file: path.relative(process.cwd(), filePath) || path.basename(filePath),
             line: lineNumber,
@@ -356,7 +388,7 @@ export function auditApxText(filePath, text, map) {
             parent: record.parentComponentType || ""
           });
           if (shouldPush) {
-            stack.push({ kind: "component", name: token, record });
+            stack.push({ kind: "component", name: token, record, props: {} });
           }
         }
       } else if (delimiter === "{" && !opaqueScope && parentComponent?.record?.groups?.[token]) {
@@ -443,7 +475,7 @@ async function writeReport(reportPath, payload) {
 }
 
 export async function runCompilerTruthAudit(options = {}) {
-  const { map, provenance } = buildCompilerContext(options.compilerOracleHome || options.oracleHome || "");
+  const { map, provenance } = loadOracleCompilerContext(options.compilerOracleHome || options.oracleHome || undefined);
   const issues = [];
   const observations = [];
   const targets = [];

package/skills/apexlang/tools/query-valid-props-context.mjs

@@ -0,0 +1,30 @@
+import { buildOracleNormalizedMap, ORACLE_NORMALIZER_VERSION, readOracleRuntimeMetadata } from "./query-valid-props-normalize.mjs";
+import { resolveOracleRuntime } from "./query-valid-props-runtime.mjs";
+
+/**
+ * Load one compiler-backed MMD context with normalized metadata and provenance.
+ */
+export function loadOracleCompilerContext(compilerOracleHome, dependencies = {}) {
+  const resolveRuntime = dependencies.resolveOracleRuntime || resolveOracleRuntime;
+  const readRuntimeMetadata = dependencies.readOracleRuntimeMetadata || readOracleRuntimeMetadata;
+  const buildNormalizedMap = dependencies.buildOracleNormalizedMap || buildOracleNormalizedMap;
+
+  const oracleRuntime = resolveRuntime(compilerOracleHome);
+  const { metadata, buildId, metadataHash } = readRuntimeMetadata(oracleRuntime.compilerJarPath);
+  const map = buildNormalizedMap({
+    metadata,
+    compilerJarPath: oracleRuntime.compilerJarPath,
+    oracleHome: oracleRuntime.oracleHome,
+    source: oracleRuntime.source
+  });
+  const provenance = {
+    buildID: buildId,
+    metadataHash,
+    normalizerVersion: ORACLE_NORMALIZER_VERSION,
+    source: oracleRuntime.source,
+    oracleHome: oracleRuntime.oracleHome,
+    compilerJar: oracleRuntime.compilerJarPath
+  };
+
+  return { map, provenance };
+}

package/skills/apexlang/tools/query-valid-props-normalize.mjs

@@ -110,6 +110,7 @@ function buildComponentRecord(componentTypeId, componentType, metadata) {
     parentDependsOn: summarizeCondition(componentType.parent?.dependingOn, metadata),
     pluginPropertyId: componentType.plugin?.propertyId || null,
     pluginComponentTypeName: componentType.plugin?.componentTypeName || null,
+    pluginApiExpression: componentType.plugin?.api?.expression || null,
     propertyCount: properties.length,
     groups,
     properties

package/skills/apexlang/tools/query-valid-props-runtime.mjs

@@ -53,9 +53,14 @@ export function findSqlOnPath({
 }
 
 /**
- * Build ordered Oracle runtime candidates from flags, environment variables, VS Code extensions, and PATH SQLcl.
+ * Build ordered Oracle runtime candidates from flags, environment variables, PATH SQLcl, and VS Code extensions.
  */
-export function collectOracleHomeCandidates(explicitOracleHome) {
+export function collectOracleHomeCandidates(explicitOracleHome, {
+  pathValue = process.env.PATH || "",
+  platform = process.platform,
+  pathExtValue = process.env.PATHEXT || ".EXE;.CMD;.BAT;.COM",
+  homeDir = os.homedir()
+} = {}) {
   const candidates = [];
   const seen = new Set();
 
@@ -82,7 +87,12 @@ export function collectOracleHomeCandidates(explicitOracleHome) {
     }
   }
 
-  const vscodeExtensionsDir = path.join(os.homedir(), ".vscode", "extensions");
+  const resolvedSqlPath = findSqlOnPath({ pathValue, platform, pathExtValue });
+  if (resolvedSqlPath) {
+    addCandidate(path.dirname(path.dirname(resolvedSqlPath)), "path_sqlcl");
+  }
+
+  const vscodeExtensionsDir = path.join(homeDir, ".vscode", "extensions");
   if (fs.existsSync(vscodeExtensionsDir)) {
     const extensionDirs = fs.readdirSync(vscodeExtensionsDir, { withFileTypes: true })
       .filter((entry) => entry.isDirectory() && entry.name.startsWith("oracle.sql-developer-"))
@@ -93,11 +103,6 @@ export function collectOracleHomeCandidates(explicitOracleHome) {
     }
   }
 
-  const resolvedSqlPath = findSqlOnPath();
-  if (resolvedSqlPath) {
-    addCandidate(path.dirname(path.dirname(resolvedSqlPath)), "path_sqlcl");
-  }
-
   return candidates;
 }