test(apex): submit an imported page and watch the exported rules fire

The verification chain could show that an approved rule was in the APEX
dictionary, and that its code raised inside an apex_session. It could not
show the thing the whole conversion rests on: that APEX's own page
processing runs the rule when a person presses a button, and puts the
message where the export said to put it. That gap is why the acceptance
notes have carried "the browser submit has not been observed" since the
first import.

apex_submit_check.py closes it, reusing the render check's disposable end
user rather than anyone's account. It fetches the page, posts it back to
wwv_flow.accept the way the browser does, and reads what came back: the
message rendered beside each field, and the messages in the notification
region. It submits twice, once with the item under test empty and once
with a valid value, because a page that rejects everything looks exactly
like a page whose rules work until you try the second case.

Two details cost an hour each, and both answer with a protection violation
that names nothing: pPageItemsProtected is one base64 string split into
".,"-separated chunks that continue each other, so decoding chunk by chunk
truncates a name at every boundary; and a protected item has to be
submitted carrying its own checksum, read from its companion input, rather
than left out.

On application 190122 all six exported validations fired with VL_PRECO
empty -- the four item rules inline beside their fields, the two record
rules in the notification, which is what their display locations said --
and 19.90 removed that rule's message while the other five stayed. The
acceptance notes now record the render and the submit, and say what is
still untested: nothing was saved, no rule outside the six was exercised,
and no layout was compared against Forms.

Author: gevianajr

docs/apex-import-verification.md

@@ -153,6 +153,34 @@ To do the same by hand, run the two PL/SQL blocks the script contains in
 SQLcl, log in with a browser as that user, save the page from the browser,
 and remove the user afterwards.
 
+### The submit
+
+A GET proves the page renders; it does not show a rule firing. The second
+half of the step does that, with the same temporary user and the same login:
+
+```
+python examples/verify/apex_submit_check.py out/render \
+    --app 190122 --page 1 --item P1_VL_PRECO --good 19.90
+```
+
+It fetches the page, posts it back to `wwv_flow.accept` the way the browser
+does — `p_json` carrying every page item — and prints, per case, the messages
+APEX rendered inline beside each field and in the notification region. It
+submits twice: once with the item under test empty, where the rule must
+reject, and once with `--good` in it, where that same rule must be gone. The
+second submit is the control; without it a page that rejects everything looks
+like a page whose rules work.
+
+Two gotchas are already paid for, and both answer with a protection violation
+rather than anything that names the cause:
+
+- `pPageItemsProtected` is one base64 string **split into `.,`-separated
+  chunks that continue each other** (`P1_TOKEN_SESS` + `AO`). Decode the
+  chunks separately and you get truncated names.
+- A protected item must be submitted **with its own checksum**, the `value` of
+  its companion `<input data-for="ITEM">`, as `ck` beside `n` and `v`.
+  Without it APEX answers *Page protection violation*.
+
 ## 5. Read the actual HTML
 
 Check the saved `render<app>_p<page>.html` for:

docs/quality-acceptance.md

@@ -57,6 +57,99 @@ FormsLang_1.2.2_x64_en-US.msi
 8E1F44C4057E9315041E1C4692DF4E125745AF9A6E0327F3AD41254F6069ED6E
 ```
 
+## Import verification on `main` (2026-09-08)
+
+The first execution of [APEX verification](apex-import-verification.md) on any
+machine. Engine at commit `e8fe949`; `9327d87` on top changes documentation
+only. Target: Oracle AI Database 26ai Free 23.26.3.0.0, APEX 26.1.0, SQLcl
+26.2.2.0, ORDS on `localhost:8080`, local workspace `FORMSLANG`, disposable
+application 190122. No customer artefact was involved. The import and
+dictionary steps used the workspace's single existing account; the render and
+submit steps each created one temporary end user and removed it in a
+`finally`.
+
+Source: `tests/fixtures/showcase/module.xml`, its six `WHEN-VALIDATE-ITEM` and
+`WHEN-VALIDATE-RECORD` units approved with a `raise_application_error` body,
+exported through `export_apexlang`. Package SHA-256
+`a9241052afc885f8e074673af8557ddc915e11ab5c0540e5eb789cd59b17de8b`.
+
+Steps 1 to 5 passed and step 6 has not been run. The authenticated render and
+the browser submit were completed later the same day, against the same
+application, and are recorded below.
+
+- **Import (step 2).** `formslang apex import` reported `Importing application
+  ID: 190122 into workspace: FORMSLANG`, `Import successful.` and `Result: OK`,
+  with no `APEXlang Compile Errors`.
+- **Dictionary (step 3).** Application 190122 holds 3 pages, 42 items, 32
+  regions, 4 processes and **6 validations**. All six are of type `PL/SQL
+  Error`, sequenced 10 to 60, with no condition and no button restriction —
+  that is, enabled and evaluated on every submit. The four item-level rules
+  carry the expected `associated_item` (`P1_VL_PRECO`, `P1_FK_CATEGORIA`,
+  `P1_CD_BARRA`, `P1_FK_FORNECEDOR`) and display
+  `INLINE_WITH_FIELD_AND_NOTIFICATION`; the two record-level rules carry no
+  item and display `INLINE_IN_NOTIFICATION`. The stored code shows the page
+  prefix rewritten from `:P0_` to `:P1_`.
+- **Label span (step 3).** The `grid_label_column_span >=
+  nvl(grid_column_span, 12)` query returned no rows.
+- **Rule execution (step 5, in the database).** In a session opened with
+  `apex_session.create_session(190122, 1, 'FORMSLANG')`, the code as stored in
+  `apex_application_page_val` for `P1_VL_PRECO` was executed twice through
+  `apex_exec.execute_plsql`. With the item empty it raised `ORA-20001:
+  VL_PRECO e obrigatorio (regra vinda do Forms).`; with the item set to
+  `19.90` it completed silently. The rule that came from the Forms trigger
+  rejects and accepts, in APEX, the same values it rejected and accepted in
+  Forms.
+- **Render (step 4).** ORDS answered both `f?p=190122:1` and
+  `/ords/r/formslang/formslang-a4/` with HTTP 200 and served the application's
+  own login page (`flow: 190122`, no `ORA-` and no `ERR-`); the authentication
+  scheme is `Oracle APEX Accounts`.
+  `examples/verify/apex_render_check.py` then created a temporary end user in
+  the workspace, logged in through `wwv_flow.accept` the way the browser does,
+  fetched page 1 with the session cookie and removed the user again. The page
+  came back **HTTP 200, 88,885 bytes** (`render190122_p1.html`): nine
+  `t-Region`s, three Interactive Grids with their headings in Forms order, 37
+  form fields, 3 Date Pickers, 15 Number Fields and two textareas, with **no**
+  error banner, no `LABEL_COLUMN_SPAN` error, no `ORA-`, no absolute
+  positioning and no layout script of FormsLang's own.
+- **Browser submit (step 4, continued).**
+  `examples/verify/apex_submit_check.py` posted that page back to
+  `wwv_flow.accept` on the same session, the way the browser's own submit does
+  — `p_json` carrying every page item, each protected item with its own
+  checksum. With `P1_VL_PRECO` empty, APEX's page-processing engine ran the
+  exported validations and **rejected the submit**: the four item-level rules
+  rendered **inline beside their fields** — `<div id="P1_VL_PRECO_error">`
+  inside the item's `t-Form-error`, with `aria-invalid="true"`,
+  `aria-describedby` and `apex-page-item-error` on the input — and again in
+  the notification region; the two record-level rules rendered in the
+  notification only. That is `inlineWithFieldAndInNotification` and
+  `inlineInNotification` behaving on screen as they were exported.
+  Submitting the same page with `P1_VL_PRECO = 19.90` removed that rule's
+  message from both places and left the other five — the negative control.
+  The same run against `P1_CD_BARRA` with a valid EAN-13 (`7891234567895`)
+  behaved identically. Saved as `submit190122_p1_empty.html` and
+  `submit190122_p1_valid.html`.
+- **What the user reads is the validation's own message.** The text on screen
+  is the validation's `errorMessage`, which FormsLang emits as a placeholder
+  (`Forms validation <unit> failed. Replace this text with the message your
+  users should see.`, `formslang/apexlang.py`), **not** the message inside the
+  rule's `raise_application_error`. A converted application therefore shows
+  placeholder text to end users until each validation's message is reworded.
+  Observed, not inferred.
+
+What this does not prove:
+
+- Anything about save behaviour. Nothing was written to a table: the page has
+  no bound form region, so there is no fetch and no DML to exercise.
+- Anything about a rule outside the six approved for this exercise, or about a
+  module other than the synthetic showcase.
+- Anything about tab order or layout fidelity against the Forms runtime. The
+  page renders cleanly; it was not compared field by field with Forms.
+
+Application 190122 remains installed in workspace `FORMSLANG`. It is
+disposable and may be deleted; step 6 is the only step still open. The
+temporary end user both scripts create is removed in a `finally`, so no test
+account survives a run — including a failed one.
+
 ## Acceptance layers
 
 | Layer | Required evidence | Boundary |
@@ -66,6 +159,7 @@ FormsLang_1.2.2_x64_en-US.msi
 | Failure recovery | Cancellation, failed providers, saved progress and crashed-job reconciliation | Existing store, workbench and AI tests; not a power-loss certification |
 | Desktop usability | Reachable header actions at 1100, 1280 and 1380 px; review, reload, Doc, Preview and export | Browser checks plus packaged-engine smoke; native installer acceptance is separate |
 | Reproducible export | Same session and configuration produce byte-identical ZIPs | Does not prove imported pages render or behave correctly |
+| Import, render and rule execution | Package imports into a disposable application with no compile errors; the APEX dictionary matches what was exported; the page renders with no error banner; a real browser submit runs the exported validations, shows the item-level ones inline beside their fields, and a valid value clears the message | Done once, 2026-09-08, for six validations on one page; no DML was exercised, and no rule outside those six |
 | Real migration | Approved private corpus, Forms runtime reference, APEX render and functional comparison | Pending; synthetic showcase is not a production corpus |
 
 ## Upgrade and recovery

examples/verify/apex_submit_check.py

@@ -0,0 +1,229 @@
+"""Submit an imported page the way the browser does, and read what came back.
+
+``apex_render_check.py`` proves the page renders. This proves the last thing
+the chain never showed: that APEX's page-processing engine runs the
+validations FormsLang exported from Forms triggers, and where the message
+lands on the screen.
+
+It logs in as the same disposable end user, GETs the page, and POSTs
+``wwv_flow.accept`` twice:
+
+1. with the item under test empty -- the rule must reject the submit;
+2. with a valid value in it -- that same rule must not appear.
+
+Both responses are saved. Nothing is written to the application.
+"""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import html as htmlmod
+import json
+import re
+import secrets as pysecrets
+import urllib.parse
+import urllib.request
+from collections import OrderedDict
+from http.cookiejar import CookieJar
+from pathlib import Path
+
+# Same directory, same disposable user, same login: this is the second half of
+# the render check, not a separate harness.
+import apex_render_check as rc
+
+ITEM_RE = re.compile(
+    r'<(input|select|textarea)\b(?P<attrs>[^>]*)>', re.IGNORECASE
+)
+ATTR_RE = re.compile(r'(\w[\w-]*)\s*=\s*"([^"]*)"')
+
+
+def form_items(page: str, page_no: int) -> OrderedDict[str, str]:
+    """Every named page item on the form, with the value the page rendered."""
+    items: OrderedDict[str, str] = OrderedDict()
+    prefix = f"P{page_no}_"
+    for m in ITEM_RE.finditer(page):
+        attrs = dict(ATTR_RE.findall(m.group("attrs")))
+        name = attrs.get("name", "")
+        if not name.startswith(prefix):
+            continue
+        # A checkbox or radio that is not checked submits nothing.
+        kind = attrs.get("type", "").lower()
+        if kind in {"checkbox", "radio"} and "checked" not in m.group("attrs").lower():
+            items.setdefault(name, "")
+            continue
+        items[name] = htmlmod.unescape(attrs.get("value", ""))
+    return items
+
+
+def item_checksums(page: str) -> dict[str, str]:
+    """item -> checksum, from the companion ``<input data-for="ITEM">``."""
+    out: dict[str, str] = {}
+    for m in ITEM_RE.finditer(page):
+        attrs = dict(ATTR_RE.findall(m.group("attrs")))
+        target = attrs.get("data-for")
+        if target and "value" in attrs:
+            out[target] = htmlmod.unescape(attrs["value"])
+    return out
+
+
+def protected_names(protected: str) -> set[str]:
+    """The item names APEX packed into pPageItemsProtected, for exclusion."""
+    # APEX breaks the base64 into ".,"-separated chunks that continue each
+    # other: decoding them one by one truncates the name on every boundary
+    # (P1_TOKEN_SESS + AO). Join first, then decode once.
+    blob = protected.split("/")[0].replace(".,", "")
+    pad = "=" * (-len(blob) % 4)
+    try:
+        text = base64.b64decode(blob + pad).decode("utf-8", "replace")
+    except Exception:  # noqa: BLE001 - an undecodable blob tells us nothing
+        return set()
+    return {n for n in text.split(":") if n}
+
+
+def inline_errors(page: str) -> list[dict]:
+    """Field-level messages, as APEX renders them beside the item."""
+    # Universal Theme renders the field-level message as
+    # <div class="t-Form-error"><div id="ITEM_error">text</div></div>, inside
+    # the item's own container -- a <span> only in older templates.
+    out = []
+    for m in re.finditer(
+        r'<(?:div|span)[^>]*\bid="(P\d+_[A-Z0-9_]+)_error"[^>]*>(.*?)</(?:div|span)>',
+        page,
+        re.DOTALL,
+    ):
+        text = re.sub(r"<[^>]+>", "", m.group(2)).strip()
+        if text:
+            out.append({"item": m.group(1), "message": htmlmod.unescape(text)})
+    return out
+
+
+def notification_errors(page: str) -> list[str]:
+    """Messages in the page-level notification region."""
+    out = []
+    for m in re.finditer(
+        r'<li[^>]*class="[^"]*a-Notification-item[^"]*"[^>]*>(.*?)</li>',
+        page,
+        re.DOTALL,
+    ):
+        text = re.sub(r"<[^>]+>", " ", m.group(1))
+        text = htmlmod.unescape(re.sub(r"\s+", " ", text)).strip()
+        if text:
+            out.append(text)
+    if not out:
+        banner = r'<div[^>]*t-Alert--danger.*?</div>\s*</div>\s*</div>'
+        for m in re.finditer(banner, page, re.DOTALL):
+            text = re.sub(r"<[^>]+>", " ", m.group(0))
+            text = htmlmod.unescape(re.sub(r"\s+", " ", text)).strip()
+            if text:
+                out.append(text[:400])
+    return out
+
+
+def submit(opener, ords: str, app: int, page_no: int, page_html: str,
+           overrides: dict[str, str], request: str) -> str:
+    """POST the page exactly as the browser's own submit does."""
+    fields = {
+        k: rc.hidden_value(page_html, k)
+        for k in ("pFlowId", "pFlowStepId", "pInstance", "pPageSubmissionId",
+                  "pSalt", "pPageItemsProtected", "pPageItemsRowVersion")
+    }
+    items = form_items(page_html, page_no)
+    items.update(overrides)
+    # A protected item travels with its own checksum -- the browser reads it
+    # from the companion <input data-for="ITEM" value="CK">. Submitting the
+    # item without its ck is a page protection violation.
+    checksums = item_checksums(page_html)
+    to_submit = []
+    for name, value in items.items():
+        entry = {"n": name, "v": value}
+        if name in checksums:
+            entry["ck"] = checksums[name]
+        to_submit.append(entry)
+    p_json = json.dumps({
+        "pageItems": {
+            "itemsToSubmit": to_submit,
+            "protected": fields["pPageItemsProtected"],
+            "rowVersion": fields["pPageItemsRowVersion"],
+            "formRegionChecksums": [],
+        },
+        "salt": fields["pSalt"],
+    })
+    body = urllib.parse.urlencode({
+        "p_flow_id": fields["pFlowId"] or str(app),
+        "p_flow_step_id": fields["pFlowStepId"] or str(page_no),
+        "p_instance": fields["pInstance"],
+        "p_page_submission_id": fields["pPageSubmissionId"],
+        "p_request": request,
+        "p_reload_on_submit": "S",
+        "p_json": p_json,
+    }).encode()
+    req = urllib.request.Request(
+        f"{ords}/wwv_flow.accept",
+        data=body,
+        headers={"Content-Type": "application/x-www-form-urlencoded",
+                 "Referer": f"{ords}/f?p={app}:{page_no}"},
+    )
+    with opener.open(req, timeout=120) as r:
+        return r.read().decode("utf-8", "replace")
+
+
+def run(args, pwd: str) -> list[dict]:
+    jar = CookieJar()
+    opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(jar))
+    opener.addheaders = [("User-Agent", "Mozilla/5.0 (FormsLang verification)")]
+    session = rc.login(opener, args.ords, args.app, args.login_page, pwd)
+    if not session:
+        return [{"ok": False, "why": "login not accepted"}]
+
+    results = []
+    for label, overrides in (
+        ("empty", {args.item: ""}),
+        ("valid", {args.item: args.good}),
+    ):
+        with opener.open(f"{args.ords}/f?p={args.app}:{args.page}:{session}", timeout=120) as r:
+            page_html = r.read().decode("utf-8", "replace")
+        answer = submit(opener, args.ords, args.app, args.page, page_html,
+                        overrides, args.request)
+        out = args.out_dir / f"submit{args.app}_p{args.page}_{label}.html"
+        out.write_text(answer, encoding="utf-8")
+        results.append({
+            "case": label,
+            f"{args.item}": overrides[args.item],
+            "file": str(out),
+            "bytes": len(answer),
+            "inline_errors": inline_errors(answer),
+            "notification_errors": notification_errors(answer),
+            "ora_20001": sorted(set(re.findall(r"ORA-20001[^<\"\\n]{0,120}", answer))),
+            "error_banner": "t-Alert--danger" in answer,
+        })
+    return results
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("out_dir", type=Path)
+    p.add_argument("--app", type=int, default=190122)
+    p.add_argument("--page", type=int, default=1)
+    p.add_argument("--item", default="P1_VL_PRECO")
+    p.add_argument("--good", default="19.90")
+    p.add_argument("--request", default="SAVE")
+    p.add_argument("--ords", default="http://localhost:8080/ords")
+    p.add_argument("--workspace", default="FORMSLANG")
+    p.add_argument("--schema", default="FORMSLANG")
+    p.add_argument("--login-page", type=int, default=9999)
+    args = p.parse_args()
+    args.out_dir.mkdir(parents=True, exist_ok=True)
+
+    sql = rc.SqlRunner()
+    pwd = "Fl" + pysecrets.token_urlsafe(18) + "9!"
+    print(rc.create_user(sql, args.workspace, args.schema, pwd))
+    try:
+        results = run(args, pwd)
+    finally:
+        print(rc.remove_user(sql, args.workspace))
+    print(json.dumps(results, indent=1, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    main()