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

[Caleb0796]

Proposal: runtime-verification guidance for the apex/apexlang skill

Summary

The apex/apexlang skill is excellent at proving a generated app compiles and imports — apex validate -input, the compiler-truth audit, problems.json, and the live-validate gate. It has comparatively little on a distinct class of defects that pass validate/import cleanly and then fail the first time a user interacts with the running app: a full-page submit rejected in the accept phase, an AJAX submit rejected by Session State Protection, ORA-22816 on an editable-grid insert, an editable-grid HTTP 400, or a failure that renders as a green success message.

The existing debugging domain covers navigation/UI drift (runtime-ui-verification.md) and generic APEX_DEBUG_MESSAGES lookup (failure-map.md), but it does not catalog these specific, preventable, documented runtime errors, and it has no data-write / submit-path verification discipline (only UI-state verification). This proposal fills that gap.

What this adds

Two new references under references/domains/debugging/, plus registration and small edits so they are discoverable through the domain's normal navigation surfaces.

1. runtime-error-catalog.md — five "passes validate/import, fails at runtime" signatures. Each entry gives the runtime signature, the cause (documented where Oracle documents it, marked observed otherwise), a generation-time rule a generator can obey to avoid emitting the defect, and how to confirm at runtime:

   • Full-page submit rejected for a display-only/protected item (Page Protection).
   • Legitimate AJAX submit rejected by Session State Protection.
   • ORA-22816 from native IG RETURNING through an INSTEAD OF trigger view.
   • Editable IG HTTP 400 (Reload on Submit).
   • A failure routed through the success-message channel (error-display correctness).

2. runtime-verification-methodology.md — agent-workflow discipline that complements runtime-ui-verification.md: validate/import success is necessary but not sufficient; "no fake greens" (a programmatic setValue/DML success is not proof the real UI path works); mechanism-proof vs end-to-end-proof; reproduce in both the DB and the live UI; re-verify review findings against the live app before acting; a self-audit ledger; and a session-health check (clearly labeled environment-observed) so an agent does not blame the artifact for a poisoned/idle tooling session.

Edited for registration and cross-linking

• failure-map.md — five new symptom→owner rows, one owner-selection rule, two anti-patterns.
• fix-patterns.md — two fix-pattern sections (runtime page-protection/submit; runtime data-write & error-path verification).
• references/domains/README.md — index bullets, trigger-coverage terms, and Failure Taxonomy entries for the new buckets.
• assets/apexlang/domains-catalog.json — debugging keywords (machine-readable routing).
• SKILL.md — one Runtime Contract bullet: validate/import success is not runtime success; run a runtime behavior pass when a change affects a page's submit/DML/AJAX/error path.

Design principles honored

• Official docs over inference. Every claim presented as documented Oracle behavior is cited to docs.oracle.com (ORA-22816; APEX_ERROR.ADD_ERROR; Reload on Submit = Only for Success; Session State Protection; Page Protection Violation).
• Observed ≠ documented. Items not in official docs are explicitly marked community/observed and never asserted as Oracle fact — e.g. the string ITEM_POSTING_VIOLATION; ORA-20987 as an SSP signature (it is a reused raise_application_error number); apex_application.g_print_success_message; the editable-IG HTTP 400 hard requirement; and the session-health narratives.
• Generic and self-contained. No environment-specific proper nouns; framed as reusable APEX guidance.
• Additive only. No existing guidance is removed or contradicted; the new files cross-reference the existing runtime-ui-verification.md.

How to validate

1. JSON parses: jq empty apex/apexlang/assets/apexlang/domains-catalog.json.
2. Cross-links resolve: every references/domains/debugging/*.md path referenced by the changed files exists.
3. Each new reference ends with ## Sources citing docs.oracle.com; failure-map.md table rows have 4 columns; git diff --check is clean.
4. Read runtime-error-catalog.md and confirm each cited Oracle URL supports the documented claim, and that each community/observed item is labeled as such.

Review performed before submission

• Adversarial technical fact-check + maintainer/convention review, with every finding independently re-verified against the files and Oracle docs before it was acted on.
• Independent second-engine (Codex) review against official Oracle documentation.
• Structural validation (JSON / links / sources / table shape / whitespace).
• A behavioral A/B check (same generation task, baseline agent vs one given these references, graded blind): both plans avoided the core error-catalog traps — a capable model already handles the common cases — and the agent given the references additionally produced an explicit end-to-end data-write verification plan (query the table after a real submit to confirm the row changed on success and did not change on a forced failure), which the baseline omitted. The added guidance changed behavior on the verification dimension.

Notes for maintainers

• This is documentation/JSON only; it adds no .apx artifacts and does not touch the validator/compiler contract (validator-fix-recipes.json is intentionally left unchanged, since these runtime errors are not compiler-emitted rule IDs).
• Commits are Signed-off-by. Per Oracle's CONTRIBUTING, merging requires the contributor to have signed the Oracle Contributor Agreement (https://oca.opensource.oracle.com).

---

Oracle's CONTRIBUTING recommends a tracking issue; I did not open one unprompted — happy to file one if maintainers prefer to discuss first.

🤖 Generated with Claude Code