pi-apexlang 0.1.0

package/skills/apexlang/references/policies/memory-bank/20-data/apex.schema-modeling.md

@@ -0,0 +1,180 @@
+# Schema Modeling — Deterministic Conventions (Plan‑Only, Oracle 23.9+/23c/23ai Aware)
+
+Purpose
+- Authoritative rules for generating schema DDL plans (no apply) with Oracle best practices.
+- Enforce deterministic naming, constraints, audit/row_version patterns, and feature gating by DB version.
+- Used by the Schema Modeling constitutional workflow to draft → critique → revise DDL scripts.
+
+Scope and Non‑negotiables
+- Plan‑only: never execute DDL; emit scripts and reviews; validation is parse‑only.
+- First agent must establish DB connection and record version/capabilities; features are gated accordingly.
+- Identifiers: unquoted snake_case, <= 30 chars, allowed [A‑Z0‑9_], avoid reserved words, ensure global uniqueness.
+- Object ordering in emission: tables → indexes (incl. FK indexes) → sequences → triggers → comments.
+- Statement terminator: every statement ends with “/” on its own line. Triggers end with “;” within body and “/” after.
+- All SQL in outputs must be in a single triple‑backticked ```sql code block where required by the workflow.
+
+Naming Conventions
+- Tables: <prefix>_<entity>
+- Constraints:
+  - PK: <prefix>_<entity>_pk
+  - UK: <prefix>_<entity>_uk[_n]
+  - FK: <prefix>_<entity>_fk[_n]
+  - CK: <prefix>_<entity>_ck[_n]
+- Indexes: <entity>_indx_n (n = 1..N), never duplicate names.
+- Triggers: <prefix>_<entity>_biu (before insert or update)
+
+Primary Keys (surrogate; NUMBER)
+- Preferred (>= 23c/23ai/23.9+): GENERATED BY DEFAULT AS IDENTITY (no sequence/trigger for PK).
+- Fallback (< 23c): sequence + before insert trigger.
+- PK column name: id NUMBER not null; PK constraint named per convention.
+
+Audit Columns and Row Version
+- Columns on every table (unless explicitly disabled):
+  - created_on DATE not null
+  - created_by VARCHAR2(255) not null
+  - updated_on DATE not null
+  - updated_by VARCHAR2(255) not null
+  - row_version INTEGER not null
+- BIU trigger responsibilities:
+  - On insert: set created_* and updated_*, initialize row_version = 1
+  - On update: increment row_version, update updated_* only
+  - Determine user with SYS_CONTEXT('APEX$SESSION','APP_USER') fallback USER
+
+Foreign Keys and Indexes
+- Always create an index for each foreign key column (or composite columns).
+- ON DELETE CASCADE only when explicitly requested; default is ON DELETE NO ACTION.
+- FK columns must be NOT NULL unless a nullable relationship is explicitly stated.
+
+Status/Lookup Strategy
+- Prefer lookup tables for status/domain values to ensure consistency and extensibility.
+- Use a foreign key to the lookup table; avoid hard‑coded CK unless trivial and stable.
+
+JSON and BOOLEAN (Feature Gating)
+- JSON:
+  - >= 23c/23ai: use JSON data type columns; optionally add JSON validity constraints when beneficial.
+  - < 23c: use CLOB with IS JSON check constraint.
+- BOOLEAN:
+  - >= 23c: BOOLEAN type permitted.
+  - < 23c: emulate with CHAR(1) and CK IN ('Y','N') or a lookup table.
+
+Temporal Types
+- Default to DATE for general timestamps; use TIMESTAMP WITH LOCAL TIME ZONE when precision/time zone required.
+- Avoid TIMESTAMP WITHOUT TZ for cross‑time‑zone data unless justified.
+
+Comments
+- Emit COMMENT ON TABLE and COMMENT ON COLUMN for every object to aid data dictionary readability.
+
+Privileges and Security
+- Do not emit GRANT/REVOKE or ACL DDL in modeling outputs; document prerequisites in reporting.
+- Never disable RLS/VPD; designs must work within existing policies.
+
+Formatting and Emission Rules
+- One object per statement block; end each with “/”.
+- Place constraints inline in CREATE TABLE where practical; use ALTER TABLE ADD CONSTRAINT when needed.
+- Generate FK indexes explicitly (CREATE INDEX …) after tables.
+- For pre‑23c fallback, place sequences and triggers after indexes.
+
+Examples (snippets; use version gating in the workflow to choose path)
+
+-- Identity PK (>= 23c)
+```sql
+create table inv_item (
+    id                            number generated by default as identity
+                                                 constraint inv_item_pk primary key
+  , name                          varchar2(255)                                 
+  , description                   varchar2(4000)                                
+  , row_version                   integer        not null                        
+  , created_on                    date           not null                        
+  , created_by                    varchar2(255)  not null                        
+  , updated_on                    date           not null                        
+  , updated_by                    varchar2(255)  not null                        
+)
+/ 
+
+comment on table inv_item is 'Inventory: items';
+/
+comment on column inv_item.name is 'Item display name';
+/
+```
+
+-- Sequence + Trigger PK (< 23c)
+```sql
+create table inv_supplier (
+    id                            number         not null
+                                                 constraint inv_supplier_pk primary key
+  , name                          varchar2(255)                                 
+  , row_version                   integer        not null                        
+  , created_on                    date           not null                        
+  , created_by                    varchar2(255)  not null                        
+  , updated_on                    date           not null                        
+  , updated_by                    varchar2(255)  not null                        
+)
+/
+create sequence inv_supplier_seq
+/
+create or replace trigger inv_supplier_biu
+  before insert or update on inv_supplier
+  for each row
+begin
+  :new.updated_on := sysdate;
+  :new.updated_by := coalesce(sys_context('APEX$SESSION','APP_USER'), user);
+  if inserting then
+    if :new.id is null then
+      select inv_supplier_seq.nextval into :new.id from dual;
+    end if;
+    :new.created_on := :new.updated_on;
+    :new.created_by := :new.updated_by;
+    :new.row_version := 1;
+  else
+    :new.row_version := nvl(:old.row_version, 0) + 1;
+  end if;
+end inv_supplier_biu;
+/
+```
+
+-- JSON and BOOLEAN (>= 23c) with fallback comments
+```sql
+create table hr_employee (
+    id                            number generated by default as identity
+                                                 constraint hr_employee_pk primary key
+  , active                        boolean                               -- <23c: use char(1) with CK or lookup
+  , profile                       json                                  -- <23c: use clob with IS JSON
+  , row_version                   integer        not null
+  , created_on                    date           not null
+  , created_by                    varchar2(255)  not null
+  , updated_on                    date           not null
+  , updated_by                    varchar2(255)  not null
+)
+/
+```
+
+-- Foreign key and index
+```sql
+alter table inv_item
+  add constraint inv_item_supplier_fk
+  foreign key ( supplier_id )
+  references inv_supplier ( id )
+/
+create index inv_item_indx_1 on inv_item ( supplier_id )
+/
+```
+
+Validation (Parse‑Only) Guidance
+- Use SQLcl with `db_connection_name` to establish the validation session.
+- Validate statements with parse‑only techniques; never execute DDL.
+- Record diagnostics with line references into checklist/reporting.
+
+Gates and Violations
+- Hard‑fail:
+  - Missing/invalid db_connection_name for this domain.
+  - Identifier length/charset violations; reserved keywords used as identifiers.
+- Defer with review:
+  - ON DELETE CASCADE not explicitly justified.
+  - Unindexed foreign keys.
+  - Non‑deterministic or non‑portable features without version gating.
+
+Compatibility with Other Rules
+- Complements 20-data/apex.sql.md (UI query rules). Keep DDL logic separate from UI SQL.
+- Follows repository governance and output policy (APEXlang domain; SQL in ```sql blocks; no UT CSS or APEX attributes here).
+
+Tags: ddl, schema, modeling, oracle, 23c, 23ai, json, boolean, identity, audit, row_version, constraints, indexes

package/skills/apexlang/references/policies/memory-bank/20-data/apex.sql.md

@@ -0,0 +1,215 @@
+# SQL Best Practices
+
+## Purpose
+Guidelines for generating clean, consistent, and maintainable SQL queries within Oracle APEX or any AI tooling-generated code.
+
+SQL snippets containing `{{...}}` are `metavariable_template` examples. Bind every variable from schema evidence before emitting SQL; do not copy unbound variables into generated artifacts.
+
+## Rules
+0. **Valid SQL**
+  - Always check the data dictionary when writing SQL queries and ensure that the table/view name and corresponding columns actually exist
+
+1. **Table Aliases**
+   - Always assign an alias to every table.
+   - Reference all columns using their alias (`s.{{source.pk}}`, `l.{{lookup.valueColumn}}`).
+   - Applies even when the query contains a single table.
+
+2. **Formatting**
+  -  Never use SQL hints
+   - Use **leading commas** in the SELECT clause:
+     ```sql
+     SELECT s.{{source.pk}}
+          , s.{{source.displayColumn}}
+          , s.{{source.amountColumn}}
+     FROM {{source.table}} s
+     ```
+   - Place **each column on its own line** for readability.
+
+3. **Join Style**
+   - Always use **ANSI SQL JOIN syntax** (`INNER JOIN`, `LEFT JOIN`, etc.).
+   - Avoid old-style comma joins or implicit joins in the WHERE clause.
+
+4. **Column Validation**
+   - Confirm every column name using the **data dictionary**.
+   - Do **not** assume column names in joined tables — validate before use.
+   - Ensure that each column has a unique name; use the foreign key reference when able to
+
+5. **Pagination and Row Limits**
+   - All report queries (Classic, IR, IG) must support pagination. Avoid unbounded datasets.
+   - Defaults are region-specific: Classic Report -> `rowRangesXToYNoPagination`; Interactive Report -> `rowRangesXToY`; Interactive Grid -> `scroll`.
+   - Provide explicit ORDER BY for deterministic pagination. Never rely on implicit ordering.
+   - Use sensible caps for `maxRowsToProcess` and page size; defaults must not be excessive.
+
+### Pagination Type Catalog (Authoritative)
+- Classic Report `pagination.type` values:
+  - `externalPaginationButtons` — External pagination controls.
+  - `nextAndPreviousLinks` — Next/previous controls.
+  - `rowRangesXToYNoPagination` — **Default**. Shows row range (X to Y).
+  - `rowRangesXToYOfZNoPagination` — Shows row range and total count (X to Y of Z).
+  - `rowRangesXToYOfZWithPagination` — Row ranges with pagination controls.
+  - `setPaginationLinks` — Pagination links.
+  - `setPaginationSearchEngine` — Search-engine style pagination.
+  - `setPaginationSelectList` — Pagination select list.
+  - Omit `pagination.type` to represent no explicit value (`null`).
+- Classic/IR `pagination.displayPosition` values (only when `pagination.type` is present):
+  - `bottomLeft`
+  - `bottomRight`
+  - `topLeft`
+  - `topRight`
+  - `topAndBottomLeft`
+  - `topAndBottomRight`
+- Interactive Report `pagination.type` values:
+  - `rowRangesXToY` — **Default**.
+  - `rowRangesXToYOfZ`
+  - Omit `pagination.type` to represent `null`.
+- Interactive Grid `pagination` values:
+  - `type`: `scroll` (**Default**) or `page`
+  - `showTotalCount`: boolean (`true`/`false`)
+  - `displayPosition` is not supported.
+
+> When a prompt specifies a pagination experience, select the closest matching region-specific catalog entry and document the choice in generated output. Otherwise, keep the region default.
+
+6. **Bind Variables and Filtering**
+   - Always use bind variables for user inputs and state (e.g., `:Pxx_ITEM`).
+   - Do not concatenate user input into SQL; avoid SQL injection vectors.
+   - Push complex filters into views where possible; UI should orchestrate, not own logic.
+   - Every non-form bind variable must map to an existing or planned page item on the same page or a documented target page.
+   - Optional filter predicates must use null-safe form, for example `(:P10_STATUS is null or o.status = :P10_STATUS)`.
+   - When comparing a page item bind against a NUMBER column in non-form SQL, use explicit numeric typing such as `to_number(:P10_CUSTOMER_ID)`.
+   - For columns ending with `_static_id`, normalize value comparisons in `WHERE` predicates using LOWER:
+     - Compliant:
+       ```sql
+       WHERE lower(r.role_static_id) = lower(:P10_ROLE_ID)
+       ```
+       ```sql
+       WHERE lower(r.role_static_id) in ('claim_adjuster', 'claim_supervisor')
+       ```
+     - Non-compliant:
+       ```sql
+       WHERE r.role_static_id = :P10_ROLE_ID
+       ```
+       ```sql
+       WHERE r.role_static_id = 'CLAIM_SUPERVISOR'
+       ```
+
+7. **Views/Packages for Business Logic**
+  - Heavy transformations/joins must live in secure views or packaged functions.
+  - The UI should select from those views; this also simplifies RLS and caching.
+  - Inline SQL size gate: if a SQL body exceeds 4000 raw characters, do not emit it directly in page DSL.
+  - Extract oversized SQL into a secure view and have the APEX artifact reference that view.
+  - Preserve only page-local predicates/order-by in the page artifact when still needed and still below the inline size limit.
+  - If a safe view definition cannot be derived from verified metadata, stop with Missing Inputs rather than inventing view DDL.
+  - Chart-focused documentation templates may inline lightweight CTEs to simulate data permutations (for example, stacking, dual-axis samples). Each CTE must document its purpose with a comment and keep datasets bounded and deterministic.
+
+8. **SELECT List and Performance Hygiene**
+   - No `SELECT *`. Project only required columns.
+   - Avoid scalar subqueries in SELECT for high-volume lists; prefer joins or pre-computed columns in views.
+   - Use appropriate indexes for facet/search/filter columns; ensure selectivity.
+  - For report SQL (Classic/IR/IG), return raw values only; do not assemble HTML markup in SQL for UI presentation.
+  - For markup placement and rendering syntax, follow `references/policies/memory-bank/30-pages/apex.report-column-rendering.md`.
+  - `SQL_PLSQL_LOB_COMPARISON_KEY_FORBIDDEN_001`: raw LOB expressions (`BLOB`, `CLOB`, `NCLOB`, `BFILE`) must not be used as comparison keys in generated SQL or PL/SQL-owned SQL.
+  - Oracle/APEX failure signature:
+    ```text
+    ORA-20999: Failed to parse SQL query! ORA-06550: line ..., column ...: ORA-22848: cannot use BLOB type as comparison key
+    ```
+  - Do not put raw LOB expressions in `GROUP BY`, `ORDER BY`, `SELECT DISTINCT`, set operations, analytic `PARTITION BY`/`ORDER BY`, equi-joins, or `WHERE`/`HAVING` comparison predicates.
+  - LOB projection/display/storage/pass-through remains allowed where the runtime component supports it; the ban is only on comparison-key use.
+  - For LOB-adjacent sort, group, filter, rank, join, or distinct intent, use deterministic scalar metadata: owning row primary key, foreign key, filename, MIME type, charset, last-updated timestamp, explicitly modeled checksum/hash, or `dbms_lob.getlength(<lob_expr>)` when the intent is file size.
+  - If aggregate or ranked output must also display a LOB, aggregate/rank in a scalar inner query first, then join back to the base row to project the LOB in the outer query.
+
+9. **Caching and Lazy Loading (Region-Level)**
+   - Prefer lazy loading for below-the-fold or auxiliary regions.
+   - Cache stable reference/LOV data; use Shared Components and APEX caching where appropriate.
+
+10. **Downloads and Export**
+   - CSV/Excel/PDF exports must be restricted by authorization scheme.
+   - Enable only formats required by the business case. PDF requires a configured printing server.
+
+11. **NLS and Format Masks**
+  - Apply date/number/currency format masks consistently and respect session/user NLS.
+  - Chart permutations should showcase supported axis `value.format` enums (`decimal`, `currency`, `percent`, `date*`, `datetime*`, `time*`) and avoid unsupported tokens.
+  - Do not embed locale-specific strings in SQL; use Text Messages for translatable content.
+
+12. **Security and RLS**
+   - Enforce Row Level Security via secure views/VPD when needed; never rely on UI-only predicates.
+   - Validate all item-driven filters server-side even if client-side validation exists.
+
+13. **APEXlang Region SQL Compatibility**
+  - Use `Type: Table` or `Type: View` for simple single-object report, cards, and content-row sources; use SQL only for joins, aggregation, computed columns, BLOB projection, contextual info, map/calendar sources, or bind predicates.
+  - Do not emit a Data Source `Name` when the source type is SQL; table/view sources must name a verified schema object.
+  - SQL for Content Row, Metric Card, Interactive Report, Map, and Calendar regions must not contain `ORDER BY`; move ordering to the region data-source attribute when supported.
+  - For SQL-backed template component regions, always use top-level `orderBy {}`. Use `type: staticValue` with `orderByClause` by default, and reserve `type: item` for a same-page item that controls the ORDER BY clause.
+  - Chart region SQL may include `ORDER BY` when needed for label/value presentation and must project exactly one label expression plus one numeric value expression per series.
+  - Contextual Info Classic Reports must use SQL that returns one effective row for the current context.
+
+14. **Canonical SQL Style for APEXlang**
+  - Prefer lowercase SQL keywords in generated APEXlang artifacts and keep each major clause on its own line.
+  - Use leading commas for select lists and align them consistently.
+  - Place each `join` and `on` predicate on separate lines; do not use comma joins.
+  - Do not use SQL hints, `select *`, or one-line SQL for generated region sources.
+  - Keep expressions Oracle-valid for the target database version; avoid unsupported aliases, non-Oracle functions, and unverified identifiers.
+
+## Pre-Validation Workflow (APEXlang generation)
+- Before generating report/form regions, validate candidate SQL against the target schema (e.g., with SQLcl) to catch identifier and join issues early.
+- Confirm that bind variables correspond to actual or planned page items (P[page]_...); remove unused binds.
+- Prefer testing with minimal row limits and explicit ORDER BY to mirror final pagination behavior.
+
+## Embedding SQL in APEXlang DSL
+- In APEXlang, SQL must be provided as a triple-backticked multi-line string placed exactly where the template expects it (e.g., sqlQuery: ```sql ... ```).
+- Do not wrap SQL in alternate code-fence syntaxes or YAML-style literals; mirror the template’s format precisely.
+- Inline SQL over 4000 raw characters is non-compliant; move it into a secure view before final output.
+- Keep business logic out of UI SQL; push heavy transformations to views/packages (see rule 7).
+
+## Identifier Case and Column/LOV Mapping
+- When defining explicit columns in content-row/cards templates, the column names must match the SQL SELECT list exactly (typically uppercase).
+- For LOV columnMapping, ensure return and display names match the database column case (commonly uppercase) to avoid invalid identifier errors.
+
+## SQLcl Pre-Validation (required for live schema work)
+- Use SQLcl directly to validate SQL before emitting final APEXlang DSL when the output depends on real schema objects.
+- Resolve `db_connection_name`, open SQLcl, and validate candidate queries against the live schema to catch identifier and join issues early.
+- Do not emit final SQL for real schema objects until live validation succeeds.
+
+## Example Seed Templates (Oracle)
+
+- List/report seed data
+  ```sql
+  WITH seed AS (
+    SELECT LEVEL AS id
+         , TRUNC(DBMS_RANDOM.VALUE(1000, 9999)) AS amount
+         , TO_CHAR(TRUNC(SYSDATE) - TRUNC(DBMS_RANDOM.VALUE(0, 365)), 'YYYY-MM-DD') AS {{source.createdOnColumn}}
+         , SUBSTR(DBMS_RANDOM.STRING('U', 8), 1, 8) AS name
+         , CASE WHEN DBMS_RANDOM.VALUE < 0.5 THEN 'ACTIVE' ELSE 'INACTIVE' END AS status
+    FROM dual
+    CONNECT BY LEVEL <= 200
+  )
+  SELECT s.id
+       , s.name
+       , s.status
+       , s.amount
+       , TO_DATE(s.{{source.createdOnColumn}}, 'YYYY-MM-DD') AS {{source.createdOnColumn}}
+  FROM seed s
+  ORDER BY {{source.createdOnColumn}} DESC, id
+  ```
+
+- LOV (display/return)
+  ```sql
+  WITH cats AS (
+    SELECT 1 AS category_id, 'Hardware' AS category_name FROM dual UNION ALL
+    SELECT 2, 'Software' FROM dual UNION ALL
+    SELECT 3, 'Services' FROM dual
+  )
+  SELECT c.category_name AS display_value
+       , c.category_id   AS return_value
+  FROM cats c
+  ORDER BY c.category_name
+  ```
+
+## Boundary with Processes and PL/SQL API Calls (Non‑Negotiable)
+- SQL guidance above governs region sources and query generation.
+- When page processes need to call PL/SQL package procedures/functions:
+  - MUST: Use process type: invokeApi with invoke { package: PKG_NAME procedureOrFunction: PROC_OR_FUNC }.
+  - MUST: Provide parameter blocks per argument with explicit direction (in | out | in out) and value mapping (item or expression with plsqlExpression).
+  - MUST NOT: Use executeCode to call packages via plsqlCode (e.g., pkg_api.proc(...)). executeCode is reserved for short anonymous blocks only when no package API exists and must be justified; violations are flagged by critique.
+- Dynamic Content regions may use plsqlFunctionBody for rendering HTML/CLOB and remain in scope of SQL/PLSQL best practices, but must not perform DML or manage transactions.
+
+Tags: sql, oracle, sqlcl, mcp, validation, random-data, sample-sql, lov, pagination, read-only

package/skills/apexlang/references/policies/memory-bank/20-data/db.connection.md

@@ -0,0 +1,93 @@
+> All `node tools/apexctl.mjs ...` commands are package-root relative: run them from the packaged skill root, or invoke that script by explicit path.
+
+# Database Connection Rules — SQLcl Direct
+
+Startup and precedence
+- Always start by reading `assets/rules-mapping.json` to load the minimum relevant rules.
+- Data rules are prioritized ahead of page/component generation:
+  - `00-guard/`
+  - `10-global/`
+  - `20-data/`
+  - `30-pages/`
+  - `40-components/`
+
+Connection contract
+- Use `db_connection_name` as the canonical saved SQLcl connection input and the corresponding APEX workspace name as required live APEXlang context.
+- For DB-backed workflows, resolve prerequisite metadata source first:
+  - inspect `assets/workspace-intelligence.json`
+  - auto-select a single eligible schema dictionary
+  - prompt the user to choose when multiple eligible schema dictionaries exist
+  - scan saved SQLcl connections before any DB-mode prompt
+  - use discovered saved connections as candidates, not as automatic approval for live work
+  - use discovered saved connections as candidates, not as automatic approval for live work
+  - prompt the user to choose when multiple saved SQLcl connections exist
+  - require the user to specify `db_connection_name` and the corresponding APEX workspace name before live metadata validation, `apex validate`, `apex import`, runtime diagnostics, or new-app materialization
+  - require the user to specify `db_connection_name` and the corresponding APEX workspace name before live metadata validation, `apex validate`, `apex import`, runtime diagnostics, or new-app materialization
+  - treat `offline` as an explicit override when the user asks for offline-only behavior
+- Record one machine-readable prerequisite state:
+  - `prereq_source: schema_doc`
+  - `prereq_source: saved_connection`
+  - `prereq_source: user_prompt`
+  - `prereq_source: unresolved`
+- Record one machine-readable connection state:
+  - `connection_source: saved_connection`
+  - `connection_source: user_prompt`
+  - `connection_source: unresolved`
+- Resolve `db_mode` after deterministic discovery for interactive DB-backed runs:
+  - `db_mode: online` requires `db_connection_name` and the corresponding APEX workspace name
+  - `db_mode: offline` is explicit and blocks live metadata/runtime work
+- Do not infer offline mode.
+- Treat `prereq_source: schema_doc` as sufficient for offline metadata reasoning only; live runtime/import still requires `db_connection_name` and the corresponding APEX workspace name.
+- Allow `prereq_source: schema_doc` and `connection_source: saved_connection` to coexist when offline schema metadata is preferred for evidence and a deterministic live connection was also discovered.
+
+How to use SQLcl
+- Support two live runtime paths:
+  - resolved build-root runtime via `apex sql` from the matching local APEX source directory
+  - PATH SQLcl runtime via `sql`
+- Record the SQLcl version for reporting, but do not treat version alone as evidence that APEX runtime commands are available.
+- Probe runtime capabilities before live APEX work and enable validate/import only when the selected runtime path is actually available.
+- Resolve the matching local APEX build root from `db_connection_name` and prefer that runtime path when it is available.
+- If build-root runtime is selected, run the live roundtrip from the resolved build directory with `apex sql`.
+- If the local first-pass check already passed and a sandboxed build-root attempt fails before real `apex validate` / `apex import` output with filesystem/setup errors such as `EPERM`, `ENOENT`, or build-root `workdir/*` write failures, treat that as an execution-environment blocker and move directly to the real live build-root roundtrip; do not keep retrying the sandbox path for that run.
+- If PATH SQLcl runtime is selected, use `sql <db_connection_name>` as the default authenticated session entrypoint.
+- If the direct alias entrypoint fails, retry with `sql /nolog` and run `connect <db_connection_name>` inside that same SQLcl session before validate/import.
+- Use `node tools/apexctl.mjs diagnostics resolve-build-root --db-connection-name <db_connection_name>` for diagnostics, reporting, or explicit build-root inspection.
+- Use SQLcl directly for schema validation and SQL verification.
+- Use SQLcl `apex` commands directly for APEXlang roundtrips.
+- Prefer built-in SQLcl or direct `apex` help over repo helper wrappers when checking command syntax or capability.
+
+Canonical roundtrip commands
+- `apex sql` from the resolved local APEX build root
+- `sql <db_connection_name>`
+- `sql /nolog`
+- `connect <db_connection_name>`
+- `apex validate -input <absolute_app_path>`
+- `apex import -input <absolute_app_path>`
+- `apex export -applicationid <application_id> -exptype APEXLANG -split -dir <absolute_export_dir>`
+- Allow validate/import only when the capability probe confirms the required commands exist in the selected runtime path.
+- Do not add `-workspaceid` to the validate/import happy path. Only add it after the active SQLcl session explicitly reports multiple-workspace ambiguity and blocks the command without a workspace override. When that happens, resolve the workspace id automatically for the active `db_connection_name` and rerun immediately.
+- When workspace-id resolution is in progress, send the user this exact short status sentence before continuing: `Identifying workspace ID for DB connection, please bare with me...`
+- Treat standalone bridge or wrapper execution as diagnostic only; the real SQLcl session is the source of truth when they disagree.
+- Do not count sandbox-only build-root filesystem/setup failures as real validate attempts for the live retry budget; only real SQLcl/compiler outcomes should feed the fix loop.
+
+Same-session requirement
+- `apex validate` and `apex import` must run in the same authenticated SQLcl user session.
+- If the session changes between validate and import, STOP and re-run validation before import.
+
+Policy and quality gates
+- Never perform live DB work if `db_connection_name` or the corresponding APEX workspace name is missing or ambiguous.
+- Never run live metadata validation, `apex validate`, or `apex import` in offline mode.
+- Never treat APEX build-root inference or SQLcl version alone as sufficient proof that live validate/import can run.
+- Ask for an environment-specific APEX build path only when automatic build-root resolution fails and the user still wants build-root runtime or diagnostics.
+- For DB object creation/update gating, enforce the canonical hard-stop rule in `references/policies/memory-bank/00-guard/ai.guard.md` (`DB_CONN_REQUIRED_001`).
+- Validate candidate SQL against the live schema when final output depends on real tables, views, columns, or joins.
+
+Prompt pattern
+- For interactive DB-backed workflows:
+  - first run deterministic discovery: inspect offline schema dictionaries and scan saved SQLcl connections
+  - if exactly one saved SQLcl connection exists, present it as the default candidate before prompting
+  - if multiple saved SQLcl connections exist, present them as selectable options
+  - use `Provide db_connection_name and the corresponding APEX workspace name for this workflow.` when live DB context is still unresolved after discovery
+  - accept `offline` only when the user explicitly asks for offline-only execution
+
+Tags: db, connection, sqlcl, oracle, connect, schema, validate, apex, roundtrip

package/skills/apexlang/references/policies/memory-bank/20-data/utplsql.rules.md

@@ -0,0 +1,44 @@
+# utPLSQL Boundary Rules (APEXlang Local Policy)
+
+## Purpose
+
+- Treat Oracle upstream DB skills at `https://github.com/oracle/skills/tree/main/db` as the main source of truth for generic utPLSQL guidance.
+- Keep this file limited to APEXlang-local boundaries for generated APEX artifacts and repository workflow safety.
+- Avoid vendoring, restating, or replacing upstream utPLSQL authoring, reporter, coverage, installation, or CI guidance.
+
+## Scope
+
+- Applies only when APEXlang or the local PL/SQL integration adapter must reason about tests for PL/SQL created from, extracted from, or used by APEX artifacts.
+- Does not make the APEXlang package a standalone utPLSQL skill or generic PL/SQL testing authority.
+- Does not authorize live test execution without the normal DB metadata, SQLcl connection, and runtime safety gates.
+
+## Local Boundary Rules
+
+- Keep utPLSQL source authoring separate from utPLSQL execution eligibility.
+- Allow test planning or test artifact authoring without a UT3 runtime in the target schema.
+- Require a UT3 preflight in the target schema before any utPLSQL run plan is treated as executable.
+- If UT3 is absent, mark execution as `blocked`; continue only with planning, package compilation checks, direct smoke checks, or reporting outputs that do not require UT3.
+- Do not frame the next step as installing utPLSQL from this package; direct generic setup guidance to upstream Oracle DB skills.
+- Never vendor utPLSQL sources into this repository or the public APEXlang package.
+
+## APEXlang-Specific Guardrails
+
+- When `app_process_api` exists or is generated by a maintenance flow, default test scope must include it.
+- Block test plans that target page-number-based package names such as `p123_*`; package names should be neutral and domain-oriented.
+- Keep test artifacts and reports under the repository artifact boundary:
+  - compact run logs under ``APEXLANG_OUTPUT_ROOT/logs/utplsql/``
+  - durable reports under ``APEXLANG_OUTPUT_ROOT/reports/utplsql/``
+- Redact credentials, full connect strings, and workspace-sensitive details from any test report or log.
+
+## Local Workflow Boundary
+
+- Local PL/SQL integration adapter testing operation:
+  - discovers local test scope,
+  - checks execution readiness,
+  - records blocked execution when prerequisites are missing,
+  - emits local reporting artifacts.
+- Local PL/SQL integration adapter maintenance operation:
+  - may emit suggested tests for extracted package APIs,
+  - does not become a generic utPLSQL design authority.
+
+Tags: utplsql, local-boundary, upstream-db-skills, app_process_api, sqlcl, artifacts

package/skills/apexlang/references/policies/memory-bank/30-pages/apex.blank-page.md

@@ -0,0 +1,13 @@
+## Blank Page Standards
+
+### Purpose
+- Provide deterministic scaffolding for blank pages that intentionally render no body regions.
+
+### Rules (Non-Negotiable)
+1. Set `pageTemplate: @/standard` with `templateOptions: #DEFAULT#` (matching the canonical blank page example).
+2. Do not add BODY regions by default; the page should only contain supporting regions such as breadcrumb if required.
+3. Apply navigation/breadcrumb policies from `apex.page.md`; include a breadcrumb region in `REGION_POSITION_01` when the application requires it.
+
+### Guidance
+- Mirror `templates/page-examples/blank-page/blank-page._index.md` for layout and optional breadcrumb region.
+- When content is later added, follow the relevant component guardrails (e.g., static content region or shared component references) instead of extending this rule file.

package/skills/apexlang/references/policies/memory-bank/30-pages/apex.calendar.md

@@ -0,0 +1,35 @@
+## Calendar Page Standards
+
+### Purpose
+- Ensure calendar pages use consistent layout, calendar region configuration, and navigation hooks.
+
+### Rules (Non-Negotiable)
+1. Use `pageTemplate: @/standard` (or documented calendar layout) with `templateOptions: #DEFAULT#`.
+2. Calendar region must use `type: calendar`, `appearance.template: @/standard`, and set required calendar attributes using the compiler-safe subset defined by the calendar template and `assets/component-attributes.json`.
+3. Every calendar region must emit `settings.pkColumn`, and that value must map to the source table primary key column used by the calendar SQL.
+4. Drag and drop may be enabled for calendars with only `startDateColumn` as well as calendars that define both `startDateColumn` and `endDateColumn`; end-date persistence is optional and only applies when an end-date column exists in the calendar contract.
+5. Calendar `settings.createLink` and `settings.viewEditLink` should use the structured object form with required `page` and optional `items`.
+6. If a user asks for `createLink`, ask whether an existing form page should be used or whether a new same-table modal form page should be created. Do not infer the form target from the current app.
+7. If a user asks for `viewEditLink`, ask whether an existing report page should be used or whether a new report page should be created. If a new report page is requested, always ask which report type to create. Do not infer the report target from the current app.
+8. Newly created `viewEditLink` report pages must include a page item that holds the calendar primary key and must filter the report SQL by that page item.
+9. If the required create-link or view-link clarification is not resolved within the single clarification round, stop with `Missing Inputs`.
+10. Use `settings.additionalCalendarViews` only for documented supplemental values `list` and `navigation`; do not restate built-in calendar views such as month, week, or day there.
+11. Apply navigation/breadcrumb standards from `apex.page.md`.
+
+### Guidance
+- Use `templates/region-components/calendar/calendar._common.md` as the canonical reference for region attributes, calendar SQL aliases, and template options; the page example remains a minimal scaffold.
+- Use `settings.displayColumn` for the event-title column mapping.
+- Use `settings.pkColumn` for the event primary key mapping, sourced from the underlying table primary key column.
+- Use structured object syntax for calendar links. Example: `createLink: { page: 5 }`, `viewEditLink: { page: 4 items: { P4_ID: &CLAIM_ID. } }`.
+- Treat page IDs, report types, and target item mappings as user intent, not something to infer from current page numbers, existing form/report pages, or alias names.
+- Calendar create links may pass the selected start timestamp with `&APEX$NEW_START_DATE.` in `createLink.items` when the target form needs date/time prefill.
+- When `createLink` results in a new page, the target must follow the modal form standards in `apex.form.md` and stay on the same base table/view as the calendar source.
+- Keep create-link date-prefill separate from drag/drop persistence: `&APEX$NEW_START_DATE.` is the create-link substitution value, while `:APEX$NEW_START_DATE` / `:APEX$NEW_END_DATE` remain drag/drop bind variables for persistence code.
+- When `viewEditLink` results in a new page, the target must be an explicitly chosen Classic Report or Interactive Report page. The page must include a dedicated PK item populated from the calendar link and the report SQL must filter by that item.
+- Do not emit `settings.showTime`; the current compiler contract does not accept it.
+- When `dragAndDrop: true`, always persist the new start date; update the end date only when the calendar/source also defines `endDateColumn`.
+- When `settings.additionalCalendarViews` is emitted, restrict it to `list`, `navigation`, or `[list navigation]`.
+- Keep whitespace-joined UT template option values atomic. For example, emit `t-Region--hideHeader js-addHiddenHeadingRoleDesc` as one `templateOptions` entry, not two separate values.
+- Keep `#DEFAULT#` separate from any additional template-option token. Never emit concatenated values such as `#DEFAULT#t-Report--stretch` or similar hybrids.
+- When older prose/examples disagree with the executable calendar templates or `assets/component-attributes.json`, the executable template plus schema contract win.
+- When adding filters or additional regions, follow the applicable component guardrails (e.g., faceted search standards).

package/skills/apexlang/references/policies/memory-bank/30-pages/apex.chart-page.md

@@ -0,0 +1,47 @@
+## Chart Page Standards
+
+### Purpose
+- Ensure chart-focused pages follow a consistent layout and use the approved chart configuration patterns.
+
+### Rules (Non-Negotiable)
+1. Set `pageTemplate: @/standard` with `templateOptions: #DEFAULT#`.
+2. For each chart region, use `type: chart`, `appearance.template: @/standard`, and series definitions that reference the chart guidance.
+3. Every `series` block inside a chart region MUST define `execution { sequence: <positive integer> }`; the sequence must be explicit and unique within that chart region.
+4. Cartesian charts (`line`, `bar`, `area`, `scatter`, `bubble`, `stock`, `range`, `pareto`) MUST declare axis children for at least `x` and `y`. Treat this as a required structural child contract, not as optional visual formatting.
+5. Each chart `axis` child MUST use the canonical APEXlang form: `axis <unique-static-id> ( name: x|y|y2 ... )`; do not emit anonymous axis blocks.
+6. Dual-axis charts MUST declare a separate `axis ... ( name: y2 )` whenever any series is assigned to the secondary Y axis.
+7. Submit controlling filter items via `pageItemsToSubmit` whenever charts depend on page items or smart filters.
+8. Apply navigation/breadcrumb requirements from `apex.page.md`.
+9. Chart `columnMapping` names MUST match the SQL output aliases exactly, including case; generated chart SQL should use uppercase or explicit semantic aliases referenced verbatim by `columnMapping`.
+
+### Guidance
+- Mirror `templates/page-examples/dashboard-page/dashboard-page._index.md` or chart-specific templates in `region-components/` for series structure, format masks, and legends.
+- Combine charts with cards or other regions using the dashboard or report guardrails as appropriate.
+- When defining chart types, set `chart { type: <chart-type> }` where `<chart-type>` is one of `bar`, `line`, `area`, `pie`, `donut`, `scatter`, `bubble`, `range`, `pareto`, or `stock`.
+- Pie and donut charts do not require cartesian axes; omit `axis` blocks unless a specific supported configuration requires them.
+- Do not treat cartesian chart axes as optional just because titles are obvious or because the chart is small. The required `axis x` and `axis y` blocks are part of the legal emitted shape.
+- When a chart depends on page items, LOV filters, or dynamic actions, list those items in `pageItemsToSubmit`; missing entries must be flagged in critique.
+- For SQL-backed chart series, alias projected columns explicitly and reference those aliases verbatim in `columnMapping`. Prefer uppercase aliases such as `LABEL`, `VALUE`, `STORE_LABEL`, and `TOTAL_VALUE`.
+- Axis format settings must use supported APEX enums (dateShort/dateMedium/dateLong/dateFull, timeShort/timeMedium/timeLong/timeFull, datetimeShort/datetimeMedium/datetimeLong/datetimeFull, decimal, currency, percent). Omit the `format` attribute for textual axes; never output `format: text`.
+- Axis tick blocks must use the canonical plural names `majorTicks` and `minorTicks`; do not emit stale singular aliases such as `majorTick` or `minorTick`.
+- For charts with dual axes or mixed series (for example, bar + line, or Y2 assignments), document the axis intent through comments or region-level advanced attributes so reviewers understand the configuration.
+- JavaScript customizations (`componentAdvanced.initJavaScriptFunction`, `dataCursor`, or legend overrides) must include a short inline comment describing the learning outcome being demonstrated, following the documentation template rule in `00-guard/ai.guard.md`.
+- Prefer declarative options for stacking, label display, and tooltip content before falling back to JavaScript; align with the chart region template upgrades.
+
+### Declarative Checklist
+- `pageItemsToSubmit`: include every item used in SQL predicates, dynamic axis calculations, or init JS snippets. For interactive documentation pages, comment which permutation the item supports.
+- `chartLayout.height` and optional `maxWidth`: size charts to fit surrounding content; avoid hard-coding width via CSS.
+- `legend` and `dataCursor`: enable these declaratively when explaining interactivity. Document why the chosen behavior matters.
+- `tooltip` and `label` blocks: showcase percentage, currency, or conditional formatting by referencing the allowed enums and masks.
+- `componentAdvanced.initJavaScriptFunction`: limit to scenarios where declarative options are insufficient; annotate behavior for readers (for example `/* docs: sync y-axis to items */`).
+- `advanced.regionDisplaySelector`: enable when the page demonstrates multiple chart variants sharing the same slot; disable if unnecessary.
+- Each chart `series`: set `execution.sequence` explicitly even for a single series; never rely on inferred ordering.
+- Each cartesian chart: emit axis blocks explicitly even if the intended axis titles are short or obvious.
+
+### Sample Page References
+- `p00002-area.apx`: Demonstrates custom legend icons via JavaScript and stacked area series. Highlights use of comments explaining the legend override.
+- `p00008-scatter.apx`: Shows dynamic Y-axis min/max driven by select lists; ensure both items are listed in `pageItemsToSubmit` and referenced in inline documentation comments.
+- `p00009-bar.apx`: Covers dual-axis configuration with data labels; annotate why the Y2 axis is used.
+- `p00024-dashboard-pies.apx`: Illustrates multiple charts sharing a page with region display selectors and collapsible explanatory regions.
+
+- Chart series may include security { authorizationScheme: ... } referencing `{your-app-alias}/shared-components/authorizations.apx` when visibility must be restricted; otherwise omit the block.