apex/apexlang: add runtime error catalog and runtime verification methodology

apex/apexlang/SKILL.md

@@ -50,6 +50,7 @@ Only the package-root asset names above are valid for the public package. Do not
 - Use `node tools/apexctl.mjs runtime preflight` from the packaged skill root to evaluate runtime candidates.
 - Use `node tools/apexctl.mjs runtime validate --app-path <absolute_app_path> --db-connection-name <db_connection_name> --apex-root <resolved_build_root> [--compiler-oracle-home <compiler_metadata_home>]` as the public check-only gate for generated apps. `--apex-root` selects the APEX/SQLcl runtime; `--compiler-oracle-home` overrides only compiler-truth metadata discovery.
 - Live APEX validation is authoritative; missing runtime inputs or live evidence records `LIVE_RUNTIME_VALIDATION_REQUIRED_001` and blocks completion.
+- Validate/import success proves the app compiles and imports, not that it behaves correctly at runtime. When a change affects a page's submit, DML, AJAX, or error-display path, run a runtime behavior pass using `references/domains/debugging/runtime-verification-methodology.md` and check the specific runtime error signatures in `references/domains/debugging/runtime-error-catalog.md` before declaring the work done.
 - Local lint, compiler-truth, and VS Code Problems snapshots are diagnostics after a live pass; missing snapshots are `not_provided`.
 - Use `problems.json` with `assets/validator-fix-recipes.json` to repair reported live problems, then rerun `runtime validate`.
 - For every APEXlang artifact generation, mutation, checking, debugging, or runtime workflow: Default to checking APEXlang code only. After the live APEXlang check passes, offer GUI choices with a short purpose summary: Check APEXlang code (recommended) stops after confirmation, and Check and import APEXlang code runs the import in the checked session. If GUI choices are unavailable, stop after checking the code and report import as a follow-up.

apex/apexlang/assets/apexlang/domains-catalog.json

@@ -115,7 +115,16 @@
         "debug id",
         "session id",
         "apex runtime error",
-        "ORA error"
+        "ORA error",
+        "ORA-22816",
+        "ORA-20987",
+        "ITEM_POSTING_VIOLATION",
+        "reload on submit",
+        "HTTP 400 on save",
+        "success message on failure",
+        "session state protection",
+        "runtime verification",
+        "data-write verification"
       ],
       "load_path": "references/domains/README.md",
       "failure_branch": true

apex/apexlang/references/domains/README.md

@@ -476,6 +476,8 @@ Use this package alongside page-patterns, page-items, buttons, and business-logi
 - `references/domains/debugging/owning-surfaces.md`
 - `references/domains/debugging/fix-patterns.md`
 - `references/domains/debugging/example-scenarios.md`
+- `references/domains/debugging/runtime-error-catalog.md`
+- `references/domains/debugging/runtime-verification-methodology.md`
 
 ### Trigger Coverage
 - `.apx validation failure`
@@ -500,6 +502,12 @@ Use this package alongside page-patterns, page-items, buttons, and business-logi
 - `session id`
 - `APEX runtime error`
 - `ORA error in running app`
+- `ITEM_POSTING_VIOLATION`
+- `ORA-20987 on submit`
+- `ORA-22816 on editable grid`
+- `HTTP 400 Reload on Submit`
+- `green success message on failure`
+- `runtime data-write verification`
 - `keyboard focus is wrong`
 - `responsive layout regression`
 
@@ -523,6 +531,11 @@ Use this package alongside page-patterns, page-items, buttons, and business-logi
 - `runtime session/wrapper artifact`
 - `runtime APEX execution-log failure`
 - `runtime UI/UX verification failure`
+- `runtime page-protection/submit violation`
+- `runtime session-state-protection rejection`
+- `runtime unsupported-RETURNING failure`
+- `runtime page-attribute misconfiguration`
+- `runtime error-display violation`
 
 ### Escalation Rules
 - Escalate to Builder JavaScript only when the failure is fetch, auth, ORDS, JWT, or other UI transport behavior.

apex/apexlang/references/domains/debugging/failure-map.md

@@ -20,6 +20,11 @@ Use this matrix after capturing the exact symptom. The goal is to identify the o
 | `APEX_DEBUG_MESSAGES` contains the error row but no useful preceding process, SQL, PL/SQL, Ajax, or call-stack context | `runtime APEX execution-log failure` | Unknown until a higher-debug reproduction exists | Ask the user to reproduce with APEX debug level set to Full trace and provide the new `PAGE_VIEW_ID` / debug id or `SESSION_ID`. |
 | Parser or file-shape failure on `.apx` input before import semantics apply | `APX syntax or file-shape failure` | The `.apx` artifact shape and local validators | Run the smallest local validator and inspect file shape before touching import packages. |
 | Validate/import succeeds but runtime navigation, current-state, focus, or visible page structure is wrong | `runtime UI/UX verification failure` | Shared components, page composition, templates, or runtime rendering depending on the snapshot evidence | Run the Chrome DevTools MCP verification loop first and map the observed runtime state before touching Builder transport or import code. |
+| Full-page submit fails in the accept phase (commonly `WWV_FLOW.ITEM_POSTING_VIOLATION`), naming a display-only or read-only page item, before any validation or process runs | `runtime page-protection/submit violation` | Page item design: a display-only/protected item is posting a value on full-page submit | Reproduce the submit with APEX debug on and confirm the failure is in the accept/item-parse phase, then apply the hidden-item + static-render rule in `references/domains/debugging/runtime-error-catalog.md` (entry 1). |
+| A legitimate AJAX item submit (cascading LOV, in-grid edit, partial submit) is rejected after import, often surfacing `ORA-20987` | `runtime session-state-protection rejection` | The submitted item's Session State Protection level, not the `.apx` compile shape | Read the actual message (ORA-20987 is an overloaded number), confirm it is an SSP/checksum rejection, then set user-editable AJAX items to Unrestricted per `references/domains/debugging/runtime-error-catalog.md` (entry 2). |
+| Editable Interactive Grid insert raises `ORA-22816` | `runtime unsupported-RETURNING failure` | Native IG DML issuing `INSERT … RETURNING` through a view with INSTEAD OF triggers | Confirm the IG source is a view with INSTEAD OF triggers and the process uses Return Primary Key after Insert, then replace the native DML with a region-bound custom process that avoids RETURNING (the grid can keep its view source) per `references/domains/debugging/runtime-error-catalog.md` (entry 3). |
+| Editable Interactive Grid save returns ORDS `HTTP 400` stating "Reload on Submit must be Only for Success" | `runtime page-attribute misconfiguration` | The page-level Reload on Submit attribute | Set the page's Reload on Submit to Only for Success on every page hosting an editable IG; this is distinct from the ORA-22816 DML issue. See `references/domains/debugging/runtime-error-catalog.md` (entry 4). |
+| A failed operation displays a green success message and still runs its close/branch behavior | `runtime error-display violation` | Error path routed through the success-message channel instead of `APEX_ERROR` | Force the failure path live and confirm it renders as an error and halts; route genuine failures through `apex_error.add_error` per `references/domains/debugging/runtime-error-catalog.md` (entry 5). |
 
 ## Owner Selection Rules
 - Prefer `import version-gate failure` when the message is about runtime version, compiler version, or import begin.
@@ -32,9 +37,12 @@ Use this matrix after capturing the exact symptom. The goal is to identify the o
 - Prefer `runtime session/wrapper artifact` when the real SQLcl session and a bridge path disagree for the same artifact and connection.
 - Prefer `runtime APEX execution-log failure` when a live running app emits an APEX/ORA error and `APEX_DEBUG_MESSAGES` can correlate it to a `PAGE_VIEW_ID`.
 - Prefer `runtime UI/UX verification failure` when the defect remains only in the running app after validate/import are already green.
+- Prefer the `runtime …` submit/interaction buckets (page-protection/submit violation, session-state-protection rejection, unsupported-RETURNING, page-attribute misconfiguration, error-display violation) when the app validated and imported cleanly but fails on a real submit, save, AJAX action, or error path; classify with `references/domains/debugging/runtime-error-catalog.md` and verify with `references/domains/debugging/runtime-verification-methodology.md`.
 
 ## Anti-Patterns
 - Do not jump to Builder JavaScript because the first visible symptom appeared in Builder.
 - Do not patch upgrade logic for a problem that happens only during import of transient input.
 - Do not patch writer ordering or omission rules before ruling out missing import canonicalization.
 - Do not treat a runtime UI symptom as an import failure when the app metadata already validates and imports cleanly.
+- Do not treat a page-protection/submit violation, an SSP rejection, an `ORA-22816`, an `HTTP 400` Reload-on-Submit error, or a green-message-on-failure as a compile or import problem: the metadata validates and imports cleanly, and the fix is a page/item design or attribute change, not an `.apx` syntax change.
+- Do not accept a green success message or a passing `apex validate`/`apex import` as proof that a submit actually persisted data; confirm the row change and reproduce in both the DB and the live UI (`references/domains/debugging/runtime-verification-methodology.md`).

apex/apexlang/references/domains/debugging/fix-patterns.md

@@ -58,6 +58,19 @@ Apply the fix pattern that matches the failure bucket. Do not spread one defect
 - Fix the owning layer that the snapshot evidence points to: shared components, page composition, templates, or runtime rendering.
 - Re-run the same runtime page and interaction path after the fix; do not accept validate/import success alone as proof.
 
+## Runtime Page-Protection Or Submit Violation
+- These defects validate and import cleanly; fix the page/item design, not the `.apx` compile shape or the import packages.
+- Do not let a display-only or protected item post a value on a full-page submit: render its value as static region content or a **Value Protected** hidden item (validate any client-set value server-side), or submit only mutable items via AJAX (see `references/domains/debugging/runtime-error-catalog.md`).
+- For an SSP rejection surfacing as `ORA-20987`, set user-editable AJAX-submitted items to Session State Protection = Unrestricted; do not restructure the artifact to compensate.
+- For `ORA-22816` on an editable grid, replace the native grid DML with a region-bound custom PL/SQL process that avoids the RETURNING clause (the grid can keep its view source).
+- For the editable-IG `HTTP 400`, set the page Reload on Submit to Only for Success.
+
+## Runtime Data-Write And Error-Path Verification
+- Do not accept `apex validate`/`apex import` success, a passing mechanism test, or a green success message as proof that a submit persisted correct data.
+- Verify the actual row change directly in the database and reproduce the same effect live in the browser; track mechanism-level and end-to-end proof separately (see `references/domains/debugging/runtime-verification-methodology.md`).
+- Route genuine failures through `apex_error.add_error` (added before the final validation/process) so they render as errors and stop the page before the success reload; never signal a failure through the success-message channel.
+- Re-verify each static or multi-agent review finding against the live app and DB before changing anything.
+
 ## Cross-Layer Alignment Rules
 - Do not change only one surface when the contract spans metadata declarations, Builder emitters, and import or export behavior.
 - Do not use upgrade logic as a shortcut for import-path compatibility.