pi-apexlang 0.2.1 → 0.3.0

package/README.md

@@ -76,6 +76,11 @@ The registered `apexlang` tool supports:
 | `runtime_doctor` | Diagnoses runtime configuration. |
 | `runtime_validate` | Runs Oracle's live check gate, then offers an interactive check-only or same-session validate-and-import choice. |
 
+`local_validate` preserves Oracle's complete validator and report semantics.
+The extension accelerates its repeated block and nesting queries in a
+process-local cache; the vendored Oracle skill remains unchanged and no checks
+are skipped.
+
 The model cannot request import as a standalone action. Oracle's skill defaults
 to checking code; only after authoritative live validation passes does the
 extension offer a separate GUI choice. Selecting **Check and import APEXlang
@@ -103,6 +108,45 @@ repeat export produces one current snapshot instead of collision copies such
 as `application_1.apx` and `p00005_1.apx`. Because this replaces the complete
 local export, preserve or import any local-only work before refreshing it.
 
+## SQLcl and ORDS compatibility advisory
+
+Oracle documents minimum APEXlang prerequisites, but does not publish an exact
+ORDS-to-SQLcl patch certification matrix. The extension therefore keeps this
+mapping advisory and records whether a row is Oracle-confirmed or an extension
+diagnostic recommendation:
+
+| Server environment | SQLcl guidance | Basis |
+| --- | --- | --- |
+| ORDS before 26.1.1 or APEX before 26.1 | APEXlang is unsupported; upgrade the server components first. | Oracle-confirmed |
+| APEX 26.1.x with ORDS 26.1.1 through 26.1.x | Oracle minimum: SQLcl 26.1. Diagnostic baseline: `26.1.2.132.1334`. | Oracle minimum plus extension advisory |
+| APEX 26.1.x with ORDS 26.2.x | Oracle does not mandate SQLcl 26.2. On mass findings, compare with `26.1.2.132.1334`. | Extension advisory |
+| Other or newer APEX, MMD, or ORDS lines | Verify current Oracle release documentation and use compiler metadata supporting the app `mmdVersion`. | Verify current docs |
+
+The complete machine-readable table, source URLs, thresholds, and the direct
+diagnostic-build download are in
+[`extensions/apexlang/ords-sqlcl-compatibility.json`](extensions/apexlang/ords-sqlcl-compatibility.json).
+The exact build is a known diagnostic baseline, not a universal pin, and SQLcl
+26.2 is not categorically blocked.
+
+When a validation result contains at least 50 structured findings, the
+extension appends the table and recommends checking:
+
+- local `sql -version`;
+- the app's `.apex/apexlang.json` `mmdVersion`;
+- the server APEX release and ORDS version with its administrator.
+
+For local and compiler-truth text reports, the mass-error signal additionally
+requires at least five distinct `.apx` files, which avoids treating one noisy
+file as an environment-wide mismatch. An explicitly unsupported MMD version
+also produces the compatibility advice. The advice never changes validation
+status, relaxes an import gate, or claims that the application is valid.
+
+[ORDS 26.1.1 introduced APEXlang support](https://www.oracle.com/tools/ords/ords-relnotes-26.1.1.html),
+[APEX 26.1 requires ORDS 26.1.1 or later](https://docs.oracle.com/en/database/oracle/apex/26.1/htmrn/changed-behavior.html),
+and Oracle's [SQLcl prerequisites](https://docs.oracle.com/en/database/oracle/sql-developer-command-line/26.1/sqcug/prerequisites-apexlang.html)
+set the SQLcl minimum at 26.1. SQLcl
+[26.1.2 added full APEXlang support](https://www.oracle.com/tools/sqlcl/sqlcl-relnotes-26.1.2.html).
+
 All app paths must remain inside the active Pi workspace. The adapter rejects
 traversal, app-tree symlinks, and multiply linked files on mutating vocabulary
 fixes; verifies live workspace input against `deployments/default.json`; and
@@ -116,8 +160,9 @@ Offline routing, templates, generation, and most local checks need Node.js
 
 Oracle documents these requirements for live APEXlang work:
 
-- Oracle APEX with APEXlang support, using the latest available 26.1 build.
-- SQLcl 26.1.2 or newer.
+- Oracle APEX 26.1 with APEXlang support.
+- ORDS 26.1.1 or newer.
+- SQLcl 26.1 or newer, selected with the compatibility advisory above.
 - Java 17 or Java 21 for SQLcl.
 - A saved SQLcl connection name and its corresponding APEX workspace name.
 - A local APEX app or authoritative schema, model, API, or table metadata.

package/extensions/apexlang/compatibility.ts

@@ -0,0 +1,227 @@
+import { readFile, rm } from "node:fs/promises";
+import { join } from "node:path";
+import compatibility from "./ords-sqlcl-compatibility.json" with { type: "json" };
+import type { ApexlangRunResult } from "../lib/apexlang-cli.mjs";
+
+type JsonRecord = Record<string, unknown>;
+
+export type ValidationCompatibilitySignal = {
+  findingCount?: number;
+  distinctFileCount?: number;
+  source: "structured-result" | "local-reports" | "compiler-truth-output" | "unsupported-mmd";
+};
+
+export const ORDS_SQLCL_COMPATIBILITY = compatibility;
+export const ORDS_SQLCL_COMPATIBILITY_TABLE = compatibility.rows;
+export const MASS_VALIDATION_FINDING_THRESHOLD = compatibility.massValidation.minimumFindings;
+export const MASS_VALIDATION_DISTINCT_FILE_THRESHOLD =
+  compatibility.massValidation.minimumDistinctFilesForAppWideReports;
+export const ORDS_SQLCL_COMPATIBILITY_GUIDELINE =
+  `When a validation action reports ${MASS_VALIDATION_FINDING_THRESHOLD}+ findings, recommend checking the server APEX/ORDS release, the app mmdVersion, and local \`sql -version\` against the extension's advisory compatibility table. For APEX 26.1, SQLcl 26.1 is Oracle's minimum and 26.1.2.132.1334 is the diagnostic baseline; do not hard-block other SQLcl versions or weaken validation/import gates.`;
+
+const VALIDATION_ACTIONS = new Set([
+  "local_validate",
+  "compiler_truth_audit",
+  "runtime_validate"
+]);
+const LOCAL_VALIDATION_REPORT_NAMES = [
+  "apexlang-dsl-report.json",
+  "apexlang-validations-report.json",
+  "apexlang-vocab-report.json"
+] as const;
+
+function asRecord(value: unknown): JsonRecord | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value as JsonRecord
+    : undefined;
+}
+
+function parseJsonRecord(value: string): JsonRecord | undefined {
+  try {
+    return asRecord(JSON.parse(value));
+  } catch {
+    return undefined;
+  }
+}
+
+function safeCount(value: unknown): number | undefined {
+  return Number.isSafeInteger(value) && Number(value) >= 0 ? Number(value) : undefined;
+}
+
+function maximumStructuredFindingCount(payload: JsonRecord): number | undefined {
+  const compatibilityFallback = asRecord(payload.compatibility_fallback);
+  const candidates = [
+    safeCount(payload.unresolved_count),
+    safeCount(payload.problem_count),
+    Array.isArray(payload.issues) ? payload.issues.length : undefined,
+    Array.isArray(payload.problems) ? payload.problems.length : undefined,
+    safeCount(compatibilityFallback?.original_unresolved_count)
+  ].filter((value): value is number => value !== undefined);
+  return candidates.length > 0 ? Math.max(...candidates) : undefined;
+}
+
+function diagnosticIdentity(issue: unknown, reportName: string, index: number): {
+  key: string;
+  file?: string;
+} {
+  if (typeof issue === "string") {
+    const raw = issue.trim();
+    const match = raw.match(/^\s*-?\s*(.+?\.apx):(\d+)(?::\d+)?:\s+[A-Z][A-Z0-9_]+\b/);
+    return { key: raw || `${reportName}:${index}`, ...(match?.[1] ? { file: match[1] } : {}) };
+  }
+
+  const record = asRecord(issue);
+  if (!record) return { key: `${reportName}:${index}:${String(issue)}` };
+  const file = typeof record.file === "string" ? record.file.trim() : "";
+  const raw = typeof record.raw === "string" ? record.raw.trim() : "";
+  const key = raw || [
+    file,
+    String(record.line ?? ""),
+    String(record.column ?? ""),
+    String(record.rule ?? record.code ?? ""),
+    String(record.message ?? "")
+  ].join(":");
+  return {
+    key: key || `${reportName}:${index}:${JSON.stringify(record)}`,
+    ...(file ? { file } : {})
+  };
+}
+
+async function readJsonReport(path: string): Promise<JsonRecord | undefined> {
+  try {
+    return parseJsonRecord(await readFile(path, "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+export async function clearLocalValidationCompatibilityReports(outputRoot: string): Promise<void> {
+  await Promise.all(
+    LOCAL_VALIDATION_REPORT_NAMES.map((name) => rm(join(outputRoot, "logs", name), { force: true }))
+  );
+}
+
+async function detectLocalReportSignal(outputRoot: string): Promise<ValidationCompatibilitySignal | undefined> {
+  const reports = await Promise.all(
+    LOCAL_VALIDATION_REPORT_NAMES.map(async (name) => ({
+      name,
+      payload: await readJsonReport(join(outputRoot, "logs", name))
+    }))
+  );
+  const vocabularyReport = reports.find(({ name }) => name === "apexlang-vocab-report.json")?.payload;
+  if (vocabularyReport?.blocking_reason === "UNSUPPORTED_MMD_VERSION") {
+    return { source: "unsupported-mmd" };
+  }
+
+  const findingKeys = new Set<string>();
+  const files = new Set<string>();
+  for (const { name, payload } of reports) {
+    for (const collection of [payload?.issues, payload?.unresolved]) {
+      if (!Array.isArray(collection)) continue;
+      collection.forEach((issue, index) => {
+        const identity = diagnosticIdentity(issue, name, index);
+        findingKeys.add(identity.key);
+        if (identity.file) files.add(identity.file);
+      });
+    }
+  }
+  if (
+    findingKeys.size >= MASS_VALIDATION_FINDING_THRESHOLD &&
+    files.size >= MASS_VALIDATION_DISTINCT_FILE_THRESHOLD
+  ) {
+    return {
+      source: "local-reports",
+      findingCount: findingKeys.size,
+      distinctFileCount: files.size
+    };
+  }
+  return undefined;
+}
+
+function detectCompilerTruthOutputSignal(output: string): ValidationCompatibilitySignal | undefined {
+  const findings = new Set<string>();
+  const files = new Set<string>();
+  for (const line of output.split(/\r?\n/)) {
+    const match = line.match(/^\s*-\s+(.+?\.apx):(\d+)(?::\d+)?:\s+([A-Z][A-Z0-9_]+)\b\s*(.*)$/);
+    if (!match?.[1]) continue;
+    findings.add(`${match[1]}:${match[2]}:${match[3]}:${match[4] ?? ""}`);
+    files.add(match[1]);
+  }
+  if (
+    findings.size >= MASS_VALIDATION_FINDING_THRESHOLD &&
+    files.size >= MASS_VALIDATION_DISTINCT_FILE_THRESHOLD
+  ) {
+    return {
+      source: "compiler-truth-output",
+      findingCount: findings.size,
+      distinctFileCount: files.size
+    };
+  }
+  return undefined;
+}
+
+export async function detectValidationCompatibilitySignal(
+  result: ApexlangRunResult
+): Promise<ValidationCompatibilitySignal | undefined> {
+  if (!VALIDATION_ACTIONS.has(result.action)) return undefined;
+
+  const payload = parseJsonRecord(result.stdout);
+  if (payload) {
+    const findingCount = maximumStructuredFindingCount(payload);
+    if (findingCount !== undefined && findingCount >= MASS_VALIDATION_FINDING_THRESHOLD) {
+      return { source: "structured-result", findingCount };
+    }
+  }
+  if (result.action === "local_validate") {
+    return detectLocalReportSignal(result.outputRoot);
+  }
+  if (result.action === "compiler_truth_audit") {
+    return detectCompilerTruthOutputSignal([result.stdout, result.stderr].filter(Boolean).join("\n"));
+  }
+  return undefined;
+}
+
+function tableCell(value: string): string {
+  return value.replaceAll("|", "\\|").replaceAll("\n", " ");
+}
+
+export function renderOrdsSqlclCompatibilityTable(): string {
+  const rows = ORDS_SQLCL_COMPATIBILITY_TABLE.map((row) => {
+    const guidance = row.diagnosticSqlclBuild && row.diagnosticSqlclDownloadUrl
+      ? `${row.sqlclGuidance} [Download ${row.diagnosticSqlclBuild}](${row.diagnosticSqlclDownloadUrl})`
+      : row.sqlclGuidance;
+    return `| ${tableCell(row.environment)} | ${tableCell(guidance)} | ${tableCell(row.basis)} |`;
+  });
+  return [
+    "| Server environment | SQLcl guidance | Basis |",
+    "| --- | --- | --- |",
+    ...rows
+  ].join("\n");
+}
+
+export function formatValidationCompatibilityAdvisory(
+  signal: ValidationCompatibilitySignal
+): string {
+  const findingSummary = signal.findingCount === undefined
+    ? "The application declares an unsupported APEXlang compiler metadata version."
+    : `Large-scale validation output detected (${signal.findingCount} findings${
+        signal.distinctFileCount === undefined ? "" : ` across ${signal.distinctFileCount} files`
+      }).`;
+  return [
+    "### SQLcl/ORDS compatibility advisory",
+    "",
+    `${findingSummary} Before changing many application files, check local \`sql -version\`, the app's \`.apex/apexlang.json\` \`mmdVersion\`, and the server APEX and ORDS versions with its administrator. A version/metadata mismatch can create broad diagnostic noise.`,
+    "",
+    renderOrdsSqlclCompatibilityTable(),
+    "",
+    compatibility.caveat,
+    "This advice does not turn a failed validation into a pass and does not authorize import."
+  ].join("\n");
+}
+
+export async function buildValidationCompatibilityAdvisory(
+  result: ApexlangRunResult
+): Promise<string> {
+  const signal = await detectValidationCompatibilitySignal(result);
+  return signal ? formatValidationCompatibilityAdvisory(signal) : "";
+}

package/extensions/apexlang/index.ts

@@ -13,6 +13,18 @@ import {
   type ApexlangInput,
   type ApexlangRunResult
 } from "../lib/apexlang-cli.mjs";
+import {
+  MASS_VALIDATION_DISTINCT_FILE_THRESHOLD,
+  MASS_VALIDATION_FINDING_THRESHOLD,
+  ORDS_SQLCL_COMPATIBILITY,
+  ORDS_SQLCL_COMPATIBILITY_GUIDELINE,
+  ORDS_SQLCL_COMPATIBILITY_TABLE,
+  buildValidationCompatibilityAdvisory,
+  clearLocalValidationCompatibilityReports,
+  detectValidationCompatibilitySignal,
+  formatValidationCompatibilityAdvisory,
+  renderOrdsSqlclCompatibilityTable
+} from "./compatibility.ts";
 
 const MAX_TOOL_OUTPUT = 80_000;
 const COMMAND_TIMEOUT_MS = 10 * 60 * 1000;
@@ -77,14 +89,20 @@ function createNewTargetProved(result: ApexlangRunResult): boolean {
     payload?.failure_class === "create_new_confirmation_required";
 }
 
-function processOutput(result: ApexlangRunResult): string {
+function processOutput(result: ApexlangRunResult, compatibilityAdvisory = ""): string {
   const streams = result.ok ? [result.stdout, result.stderr] : [result.stderr, result.stdout];
-  return trimOutput(streams.filter(Boolean).join("\n").trim(), result.outputRoot);
+  const output = trimOutput(streams.filter(Boolean).join("\n").trim(), result.outputRoot);
+  return [output, compatibilityAdvisory].filter(Boolean).join("\n\n");
 }
 
-function failureOutput(result: ApexlangRunResult, fallback: string): string {
-  const output = processOutput(result) || fallback;
-  return `${output}\n\nAPEXlang reports: ${result.outputRoot}`;
+function failureOutput(
+  result: ApexlangRunResult,
+  fallback: string,
+  compatibilityAdvisory = ""
+): string {
+  const streams = result.ok ? [result.stdout, result.stderr] : [result.stderr, result.stdout];
+  const output = trimOutput(streams.filter(Boolean).join("\n").trim(), result.outputRoot) || fallback;
+  return `${[output, compatibilityAdvisory].filter(Boolean).join("\n\n")}\n\nAPEXlang reports: ${result.outputRoot}`;
 }
 
 type ApexlangDependencies = {
@@ -113,6 +131,7 @@ export function createApexlangTool(overrides: Partial<ApexlangDependencies> = {}
     "Load the apexlang skill before using the apexlang tool and follow its routing and Missing Inputs rules.",
     "Use apexlang workspace_probe before app-scoped APEXlang work.",
     EXPORT_OVERWRITE_GUIDELINE,
+    ORDS_SQLCL_COMPATIBILITY_GUIDELINE,
     "Use apexlang runtime_validate only after the user provides both db_connection_name and the matching APEX workspace_name; import requires the tool's separate post-check GUI choice."
   ],
   executionMode: "sequential",
@@ -194,11 +213,25 @@ export function createApexlangTool(overrides: Partial<ApexlangDependencies> = {}
       ...(signal ? { signal } : {}),
       timeoutMs: COMMAND_TIMEOUT_MS
     };
+    if (input.action === "local_validate") {
+      await clearLocalValidationCompatibilityReports(outputRoot);
+    }
     const result = await dependencies.run(input, runOptions);
-    const output = processOutput(result);
+    const compatibilityAdvisory = await buildValidationCompatibilityAdvisory(result);
+    if (compatibilityAdvisory) {
+      onUpdate?.({
+        content: [{ type: "text", text: compatibilityAdvisory }],
+        details: { action: input.action, compatibilityAdvisory: true }
+      });
+    }
+    const output = processOutput(result, compatibilityAdvisory);
     if (!result.ok) {
       throw new Error(
-        failureOutput(result, `APEXlang ${input.action} failed with exit code ${result.code}.`)
+        failureOutput(
+          result,
+          `APEXlang ${input.action} failed with exit code ${result.code}.`,
+          compatibilityAdvisory
+        )
       );
     }
 
@@ -207,7 +240,8 @@ export function createApexlangTool(overrides: Partial<ApexlangDependencies> = {}
         throw new Error(
           failureOutput(
             result,
-            "APEXlang runtime validation did not produce authoritative live pass evidence."
+            "APEXlang runtime validation did not produce authoritative live pass evidence.",
+            compatibilityAdvisory
           )
         );
       }
@@ -299,10 +333,12 @@ export function createApexlangTool(overrides: Partial<ApexlangDependencies> = {}
             expectedAppDigest
           });
           if (!createNewTargetProved(proofResult)) {
+            const proofCompatibilityAdvisory = await buildValidationCompatibilityAdvisory(proofResult);
             throw new Error(
               failureOutput(
                 proofResult,
-                "Oracle did not prove that the create-new target is absent from the selected workspace."
+                "Oracle did not prove that the create-new target is absent from the selected workspace.",
+                proofCompatibilityAdvisory
               )
             );
           }
@@ -343,12 +379,14 @@ export function createApexlangTool(overrides: Partial<ApexlangDependencies> = {}
           createNewConfirmed,
           expectedAppDigest
         });
-        const importOutput = processOutput(importResult);
+        const importCompatibilityAdvisory = await buildValidationCompatibilityAdvisory(importResult);
+        const importOutput = processOutput(importResult, importCompatibilityAdvisory);
         if (!liveImportPassed(importResult)) {
           throw new Error(
             failureOutput(
               importResult,
-              "APEXlang validate-and-import did not produce authoritative import pass evidence."
+              "APEXlang validate-and-import did not produce authoritative import pass evidence.",
+              importCompatibilityAdvisory
             )
           );
         }
@@ -429,11 +467,21 @@ export {
   IMPORT_CHOICE,
   CREATE_NEW_CHOICE,
   EXPORT_OVERWRITE_GUIDELINE,
+  MASS_VALIDATION_DISTINCT_FILE_THRESHOLD,
+  MASS_VALIDATION_FINDING_THRESHOLD,
+  ORDS_SQLCL_COMPATIBILITY,
+  ORDS_SQLCL_COMPATIBILITY_GUIDELINE,
+  ORDS_SQLCL_COMPATIBILITY_TABLE,
   UPDATE_EXISTING_CHOICE,
   actionWritesProject,
+  buildValidationCompatibilityAdvisory,
+  clearLocalValidationCompatibilityReports,
   confirmationMessage,
   createNewTargetProved,
+  detectValidationCompatibilitySignal,
+  formatValidationCompatibilityAdvisory,
   liveImportPassed,
-  liveValidationPassed
+  liveValidationPassed,
+  renderOrdsSqlclCompatibilityTable
 };
 export type { ApexlangAction };

package/extensions/apexlang/ords-sqlcl-compatibility.json

@@ -0,0 +1,67 @@
+{
+  "schemaVersion": 1,
+  "policy": "advisory-only",
+  "lastReviewed": "2026-07-19",
+  "massValidation": {
+    "minimumFindings": 50,
+    "minimumDistinctFilesForAppWideReports": 5
+  },
+  "caveat": "Oracle publishes minimum APEXlang prerequisites, not an ORDS-to-SQLcl patch certification matrix. Exact SQLcl builds in this table are diagnostic baselines and never validation gates.",
+  "rows": [
+    {
+      "environment": "ORDS before 26.1.1 or APEX before 26.1",
+      "matchMode": "any",
+      "ordsRange": "<26.1.1",
+      "apexRange": "<26.1",
+      "sqlclGuidance": "APEXlang is unsupported; upgrade the server components before changing SQLcl.",
+      "diagnosticSqlclBuild": "",
+      "diagnosticSqlclDownloadUrl": "",
+      "basis": "oracle-confirmed",
+      "sourceUrls": [
+        "https://www.oracle.com/tools/ords/ords-relnotes-26.1.1.html",
+        "https://docs.oracle.com/en/database/oracle/apex/26.1/htmrn/changed-behavior.html"
+      ]
+    },
+    {
+      "environment": "APEX 26.1.x with ORDS 26.1.1 through 26.1.x",
+      "matchMode": "all",
+      "ordsRange": ">=26.1.1 <26.2.0",
+      "apexRange": "26.1.x",
+      "sqlclGuidance": "Oracle minimum: SQLcl 26.1. Diagnostic baseline: 26.1.2.132.1334.",
+      "diagnosticSqlclBuild": "26.1.2.132.1334",
+      "diagnosticSqlclDownloadUrl": "https://download.oracle.com/otn_software/java/sqldeveloper/sqlcl-26.1.2.132.1334.zip",
+      "basis": "oracle-minimum-plus-extension-advisory",
+      "sourceUrls": [
+        "https://docs.oracle.com/en/database/oracle/sql-developer-command-line/26.1/sqcug/prerequisites-apexlang.html",
+        "https://www.oracle.com/tools/sqlcl/sqlcl-relnotes-26.1.2.html"
+      ]
+    },
+    {
+      "environment": "APEX 26.1.x with ORDS 26.2.x",
+      "matchMode": "all",
+      "ordsRange": ">=26.2.0 <26.3.0",
+      "apexRange": "26.1.x",
+      "sqlclGuidance": "Oracle does not mandate SQLcl 26.2. On mass findings, compare with diagnostic baseline 26.1.2.132.1334.",
+      "diagnosticSqlclBuild": "26.1.2.132.1334",
+      "diagnosticSqlclDownloadUrl": "https://download.oracle.com/otn_software/java/sqldeveloper/sqlcl-26.1.2.132.1334.zip",
+      "basis": "extension-advisory",
+      "sourceUrls": [
+        "https://docs.oracle.com/en/database/oracle/sql-developer-command-line/26.1/sqcug/prerequisites-apexlang.html",
+        "https://www.oracle.com/tools/sqlcl/sqlcl-downloads.html"
+      ]
+    },
+    {
+      "environment": "Other or newer APEX, MMD, or ORDS release lines",
+      "matchMode": "fallback",
+      "ordsRange": "other",
+      "apexRange": "other",
+      "sqlclGuidance": "Verify current Oracle release documentation and use SQLcl compiler metadata that supports the app mmdVersion.",
+      "diagnosticSqlclBuild": "",
+      "diagnosticSqlclDownloadUrl": "",
+      "basis": "verify-current-docs",
+      "sourceUrls": [
+        "https://docs.oracle.com/en/database/oracle/apex/26.1/apxdc/using-sqlcl-apexlang.html"
+      ]
+    }
+  ]
+}

package/extensions/lib/apexlang-cli.mjs

@@ -21,6 +21,7 @@ export const APEXLANG_ACTIONS = Object.freeze([
 
 const apexctlPath = resolve(APEXLANG_SKILL_ROOT, "tools/apexctl.mjs");
 const queryValidPropsPath = resolve(APEXLANG_SKILL_ROOT, "tools/query-valid-props.mjs");
+const localValidatePath = resolve(moduleDirectory, "apexlang-local-validate.mjs");
 const runtimeRoundtripPath = resolve(moduleDirectory, "apexlang-runtime-roundtrip.mjs");
 const sqlclPtyProxyPath = resolve(moduleDirectory, "apexlang-sqlcl-pty.py");
 const CONTROL_CHARACTER_PATTERN = /[\u0000-\u001f\u007f]/;
@@ -214,9 +215,9 @@ export function buildApexlangCommand(input) {
   }
 
   if (action === "local_validate") {
-    const args = ["apexlang", "validate", "--app-path", requirePath(input, "app_path", action)];
+    const args = ["--app-path", requirePath(input, "app_path", action)];
     addFlag(args, "--fix-vocab", input.fix_vocab);
-    return apexctl(args);
+    return { scriptPath: localValidatePath, args, prelude: [] };
   }
 
   if (action === "compiler_truth_audit") {

package/extensions/lib/apexlang-local-validate.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import { mkdirSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const moduleDirectory = dirname(fileURLToPath(import.meta.url));
+const skillRoot = resolve(moduleDirectory, "../../skills/apexlang");
+const runtimeRoot = resolve(skillRoot, "runtime");
+const pythonRoot = resolve(runtimeRoot, "internal/python");
+const optimizedDslValidator = resolve(moduleDirectory, "apexlang-local-validator.py");
+
+function readOption(args, name) {
+  const index = args.indexOf(name);
+  return index >= 0 && index + 1 < args.length ? String(args[index + 1]).trim() : "";
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const appPath = readOption(args, "--app-path");
+  if (!appPath) {
+    console.error("Missing required --app-path");
+    return 1;
+  }
+
+  const outputRoot = String(process.env.APEXLANG_OUTPUT_ROOT ?? "").trim();
+  if (!outputRoot) {
+    console.error("APEXLANG_OUTPUT_ROOT is required in packaged apexlang runtime");
+    return 1;
+  }
+
+  const reportDir = resolve(outputRoot, "logs");
+  mkdirSync(reportDir, { recursive: true });
+  const fixVocab = args.includes("--fix-vocab");
+  const commands = [
+    [
+      resolve(pythonRoot, "validate_apexlang_vocab.py"),
+      [
+        "--app-path",
+        appPath,
+        "--report-path",
+        join(reportDir, "apexlang-vocab-report.json"),
+        fixVocab ? "--rewrite" : "--check-only"
+      ]
+    ],
+    [
+      optimizedDslValidator,
+      ["--report-path", join(reportDir, "apexlang-dsl-report.json"), appPath]
+    ],
+    [
+      resolve(pythonRoot, "validate_validations.py"),
+      ["--report-path", join(reportDir, "apexlang-validations-report.json"), appPath]
+    ]
+  ];
+
+  let failures = 0;
+  for (const [scriptPath, scriptArgs] of commands) {
+    const result = spawnSync("python3", [scriptPath, ...scriptArgs], {
+      cwd: process.cwd(),
+      encoding: "utf8",
+      env: {
+        ...process.env,
+        APEXLANG_EMBEDDED_TOOLS_ROOT: resolve(skillRoot, "tools"),
+        APEXLANG_PACKAGE_ROOT: skillRoot,
+        APEXLANG_RUNTIME_ROOT: runtimeRoot,
+        PYTHONDONTWRITEBYTECODE: "1"
+      }
+    });
+    if (result.stdout) process.stdout.write(result.stdout);
+    if (result.stderr) process.stderr.write(result.stderr);
+    if (typeof result.status !== "number" || result.status !== 0) failures += 1;
+  }
+
+  if (failures > 0) {
+    console.log("APEXLANG_LOCAL_CHECK_FAILED");
+    return 1;
+  }
+  console.log("APEXLANG_LOCAL_CHECK_OK");
+  return 0;
+}
+
+process.exitCode = main();

package/extensions/lib/apexlang-local-validator.py

@@ -0,0 +1,116 @@
+#!/usr/bin/env python3
+"""Run Oracle's DSL validator with per-process parser acceleration.
+
+The vendored Oracle skill stays byte-for-byte unchanged. This launcher imports
+its validator, replaces only pure parsing helpers with equivalent cached
+implementations, and then calls the original command-line entry point.
+"""
+
+from __future__ import annotations
+
+from bisect import bisect_right
+from functools import lru_cache, wraps
+import importlib.util
+import os
+from pathlib import Path
+import sys
+from types import ModuleType
+from typing import Any, Callable
+
+
+class _SparseDepthIndex:
+    """Store lexical depth checkpoints only at offsets requested by validators."""
+
+    __slots__ = ("positions", "states")
+
+    def __init__(self) -> None:
+        self.positions: list[int] = [0]
+        self.states: list[tuple[int, int, bool]] = [(0, 0, False)]
+
+
+_DEPTH_INDEXES: dict[str, _SparseDepthIndex] = {}
+
+
+def _sparse_nesting_depth(text: str, idx: int) -> tuple[int, int]:
+    """Return Oracle-compatible nesting depth using the closest prior checkpoint."""
+    target_idx = min(len(text), idx) if idx >= 0 else max(0, len(text) + idx)
+    index = _DEPTH_INDEXES.setdefault(text, _SparseDepthIndex())
+    checkpoint_slot = bisect_right(index.positions, target_idx) - 1
+    start = index.positions[checkpoint_slot]
+    paren_depth, brace_depth, in_string = index.states[checkpoint_slot]
+
+    for pos in range(start, target_idx):
+        ch = text[pos]
+        if ch == '"' and (pos == 0 or text[pos - 1] != "\\"):
+            in_string = not in_string
+            continue
+        if in_string:
+            continue
+        if ch == "(":
+            paren_depth += 1
+        elif ch == ")":
+            paren_depth = max(0, paren_depth - 1)
+        elif ch == "{":
+            brace_depth += 1
+        elif ch == "}":
+            brace_depth = max(0, brace_depth - 1)
+
+    if start != target_idx:
+        insert_at = checkpoint_slot + 1
+        index.positions.insert(insert_at, target_idx)
+        index.states.insert(insert_at, (paren_depth, brace_depth, in_string))
+    return paren_depth, brace_depth
+
+
+def _validator_path() -> Path:
+    runtime_override = os.environ.get("APEXLANG_RUNTIME_ROOT", "").strip()
+    runtime_root = (
+        Path(runtime_override).resolve()
+        if runtime_override
+        else Path(__file__).resolve().parents[2] / "skills" / "apexlang" / "runtime"
+    )
+    return runtime_root / "internal" / "python" / "validate_apexlang.py"
+
+
+def _load_oracle_validator(path: Path) -> ModuleType:
+    sys.path.insert(0, str(path.parent))
+    spec = importlib.util.spec_from_file_location("_pi_apexlang_oracle_validator", path)
+    if spec is None or spec.loader is None:
+        raise RuntimeError(f"Cannot load Oracle APEXlang validator: {path}")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+def _cache_list_function(function: Callable[..., list[Any]]) -> Callable[..., list[Any]]:
+    """Cache immutable results while preserving Oracle's fresh-list return type."""
+    cached = lru_cache(maxsize=None)(lambda *args: tuple(function(*args)))
+
+    @wraps(function)
+    def wrapper(*args: Any) -> list[Any]:
+        return list(cached(*args))
+
+    return wrapper
+
+
+def _accelerate(module: ModuleType) -> None:
+    module.nesting_depth = _sparse_nesting_depth
+    for name in (
+        "find_component_blocks",
+        "find_named_brace_blocks",
+        "find_immediate_component_blocks",
+        "find_immediate_named_brace_blocks",
+    ):
+        setattr(module, name, _cache_list_function(getattr(module, name)))
+    module.block_body = lru_cache(maxsize=None)(module.block_body)
+
+
+def main(argv: list[str]) -> int:
+    validator = _load_oracle_validator(_validator_path())
+    _accelerate(validator)
+    return int(validator.main(argv))
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-apexlang",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "APEXlang support for pi, powered by Oracle's public APEXlang skill.",
   "type": "module",
   "license": "UPL-1.0",