pi-apexlang 0.2.2 → 0.4.0

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

@@ -42,8 +42,8 @@
   - Dynamic actions `DA_<purpose>`
 - SQL and PL/SQL must use named notation, and appear inside fenced blocks. Process-type policy split: page processes default to `invokeApi`, appProcess remains `executeCode`-only, and a thin page-level `executeCode` wrapper is allowed only for page-coupled loaders or branch-gated flows when direct page-item assignment is the reliable runtime-safe choice.
 - Prefer declarative shapes over PL/SQL when the workflow can be expressed through supported native APEX DSL/process constructs.
-- Advisory threshold: for any PL/SQL text block longer than 4000 raw characters, emit `PLSQL_LENGTH_WARN_001` and recommend extraction into a package API (`app_process_api` default) plus page-process `invokeApi` or a justified thin wrapper exception (appProcess stays `executeCode`). This warning is non-blocking.
-- Advisory threshold: for any inline SQL block longer than 4000 raw characters, emit `SQL_LENGTH_WARN_001` and recommend extraction into a secure view that the page artifact references instead of embedding the full query inline. This warning is non-blocking.
+- Hard limit: a PL/SQL text block longer than 4000 raw characters violates `PLSQL_INLINE_BLOCK_001`; extract it into a package API (`app_process_api` default) plus page-process `invokeApi` or a justified thin wrapper exception (`appProcess` stays `executeCode`). This finding blocks final output.
+- Hard limit: an inline SQL block longer than 4000 raw characters violates `SQL_INLINE_BLOCK_001`; extract it into a secure view that the page artifact references instead of embedding the full query inline. This finding blocks final output.
 
 ## 3. Processes
 - **Execution points:**
@@ -112,7 +112,7 @@ validation [validationStaticId] (
   - Server execution: `da-execute-server-side-code.apx`, `da-delete-with-notification.apx`
   - Alert/Confirm: `da-alert-confirm-cancel.apx`
   - Timer, slider, debounce/throttle, plugin styling: see dedicated templates
-- Server-side work should be packaged and referenced via `invokeApi` by default; use a thin page-level `executeCode` wrapper only when the page must assign items directly in a runtime-safe loader or branch flow, and keep inline business logic out of that wrapper. Critique must warn when inline PL/SQL exceeds 4000 raw characters and fail when existing non-negotiable rules are violated.
+- Server-side work should be packaged and referenced via `invokeApi` by default; use a thin page-level `executeCode` wrapper only when the page must assign items directly in a runtime-safe loader or branch flow, and keep inline business logic out of that wrapper. Critique must hard-fail inline PL/SQL over 4000 raw characters under `PLSQL_INLINE_BLOCK_001`.
 - Use specific `itemsToSubmit`; avoid broad lists.
 - AI assistant settings note:
   - Prefer `genAI { agent: @AGENT }` referencing an existing AI agent alias (for example `@home`).

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

@@ -12,17 +12,15 @@ Startup and precedence
   - `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.
+- Use `db_connection_name` as the canonical saved SQLcl connection input. Resolve workspace identity from the active runtime for existing apps; require an exact destination workspace name before new-app materialization.
 - 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
+  - auto-bind exactly one deterministic saved connection 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
+  - request manual `db_connection_name` only when saved-connection discovery cannot resolve one; require an exact workspace name only for new-app materialization or after runtime-reported ambiguity
   - treat `offline` as an explicit override when the user asks for offline-only behavior
 - Record one machine-readable prerequisite state:
   - `prereq_source: schema_doc`
@@ -34,10 +32,10 @@ Connection contract
   - `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: online` requires a resolved `db_connection_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.
+- Treat `prereq_source: schema_doc` as sufficient for offline metadata reasoning only; live runtime/import still requires a resolved `db_connection_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
@@ -66,7 +64,7 @@ Canonical roundtrip commands
 - `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...`
+- When workspace-id resolution is in progress, send the user this exact short status sentence before continuing: `Identifying workspace ID for the DB connection, please bear 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.
 
@@ -75,7 +73,7 @@ Same-session requirement
 - 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 perform live DB work if `db_connection_name` is unresolved. Require workspace input only for new-app materialization or when runtime ambiguity cannot be resolved deterministically.
 - 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.
@@ -85,9 +83,9 @@ Policy and quality gates
 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 exactly one saved SQLcl connection exists, auto-bind it
   - 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
+  - use `Provide db_connection_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/30-pages/apex.cards-page.md

@@ -0,0 +1,95 @@
+# APEX Visual Summary Cards Page
+
+## Purpose
+
+Defines the deterministic page pattern for visual summaries of people, products, statuses, or other entities rendered with one native APEX Cards region. This pattern owns Cards composition only; it does not orchestrate filtering or search.
+
+## Pattern Selection
+
+- Select this pattern for people cards, product cards, status tiles, entity cards, or an explicit native Cards region.
+- Use a Metric Card template-component region instead for aggregate KPIs or a normalized metric strip unless the request explicitly requires native Cards.
+- Use a report pattern instead when dense comparison, sorting, or tabular scanning is the primary task.
+- Do not add Faceted Search, Smart Filters, search items, facets, or filter dynamic actions under this pattern. Route a separate filtering/search request to its owning pattern.
+
+Rule ID: `CARDS_VISUAL_SUMMARY_PATTERN_REQUIRED_001`.
+
+## Source-to-Attribute Plan
+
+Before rendering APEXlang, record one mapping row for every requested Cards role:
+
+| Cards role | Required evidence | Native mapping |
+|---|---|---|
+| Title | SQL projection alias or REST data-profile column | `title.column`, or `title.htmlExpression` with `advancedFormatting: true` |
+| Subtitle | SQL projection alias or REST data-profile column | `subtitle.column` or advanced formatting |
+| Body | SQL projection alias or REST data-profile column | `body.column` or advanced formatting |
+| Secondary body | SQL projection alias or REST data-profile column | `secondaryBody.column` or advanced formatting |
+| Row identity | Proven primary-key or stable REST identity field | `card.primaryKeyColumn1` and optional `primaryKeyColumn2` when the source has a composite identity or BLOB media requires it |
+| Icon | Pinned Font APEX token, projected icon-class column, or projected initials | `iconAndBadge` |
+| Image | Raw BLOB alias, projected URL alias, or explicit direct URL | `media`, plus `blobAttributes` only for BLOB media |
+| Badge | Projected metric or status alias | `iconAndBadge.badgeColumn` with optional label/classes |
+| Link | Proven target page and target-item/source-column mapping | Native Cards `action` with declarative `behavior.target` |
+| Conditional style | Projected, allowlisted semantic class token | The narrowest compiler-proven `cssClasses` property; never raw user-authored CSS |
+
+- SQL-backed Cards use exactly `location: localDatabase`, `type: sqlQuery`, and a fenced `sqlQuery`; they must not also declare `restSource`. Every mapped alias must be present in the query projection and every referenced object/column must have DB object evidence.
+- REST-backed Cards use exactly `location: restSource` plus `restSource: @alias`; they omit SQL `type` and `sqlQuery`. They require an existing REST Data Source plus an authoritative data profile. Map the profile's actual column names; do not infer JSON paths or aliases.
+- A requested role with no proven source field is `unresolved`. Omit an optional unresolved role or stop with `Missing Inputs` when it is required by the request.
+- Prefer direct `column` mapping with `advancedFormatting: false`. Use `htmlExpression` only for a requested composition that cannot be represented by one native column, set `advancedFormatting: true`, and escape text substitutions with `!HTML`.
+
+Rule ID: `CARDS_SOURCE_MAPPING_REQUIRED_001`.
+
+## Icons, Badges, and Conditional Styles
+
+- Prefer `iconSource: iconClassColumn` for row-dependent icons and `iconSource: initials` for people cards with initials. A fixed icon must come from the pinned Font APEX catalog.
+- Prefer `badgeColumn` for row-dependent status or metric text. Keep the badge label concise and omit it when the value is self-explanatory.
+- For conditional styling, project only `u-normal`, `u-hot`, `u-info`, `u-success`, `u-warning`, `u-danger`, or `NULL`. Map the proven alias to `card.cssClasses`; do not accept a raw class column. For REST profiles, record the exact finite set in the mapped profile column's `comments.comments` as `authoritative-profile-enum: [...]`; absence of that evidence blocks conditional styling.
+- Do not concatenate arbitrary CSS, accept CSS tokens from untrusted end-user input, invent Universal Theme classes, or use HTML badge markup when native badge mapping is sufficient.
+- If compiler truth for the active build does not expose a safe property for the requested conditional style, preserve the status as text/badge content and stop before inventing a styling workaround.
+
+## Interactivity
+
+- Clickable cards use a native Cards action with `type: fullCard`, `layout.sequence`, `behavior.type: redirectThisApp`, and a declarative same-app target. Every source substitution used by the target must be projected by the Cards source.
+- Other supported action presentations are `title`, `subtitle`, `media`, and `button`. Only `button` requires a concise `label` and `layout.position: primary | secondary`; non-button actions omit both fields.
+- Button actions may use `appearance.displayType: text | icon | textWithIcon`, with `appearance.icon` required for icon presentations, plus `hot` and `cssClasses`. Any action may carry `advanced.staticId` and a compiler-backed `serverSideCondition`.
+- `behavior.type: triggerAction` omits `behavior.target` and `behavior.targetUrl` and requires a nested `triggerAction` child with its supported UI action reference. Redirect actions use only their matching target shape.
+- If full-card navigation and a decision button compete for the same card, document the intended precedence and evidence-backed conditions in the UX contract. Do not infer mutually exclusive business conditions from the presence of both actions.
+- Dynamic refresh must name both the trigger and the Cards region static ID. Use the supported dynamic-action Refresh capability and target only that Cards region.
+- When refreshed SQL depends on page items, list those items in `source.pageItemsToSubmit`. Do not rely on stale browser or session state.
+- A refresh after a modal create/edit closes is required when the changed row should appear in or disappear from the Cards result set.
+- Use Cards-owned `cards.refresh-on-change.md` for item-change refresh and `cards.refresh-after-dialog.md` for dialog-close refresh. Do not modify or synthesize behavior from shared Dynamic Action templates.
+
+## Security
+
+- Cards pages inherit the authenticated-page and session-protection baseline. Add an existing region authorization scheme when the Cards source is more restricted than the page, and authorize target pages/processes independently.
+- Prefer native text mappings. Every database or REST value inserted into an advanced HTML expression must use `&COLUMN!HTML.`; never use unescaped `&COLUMN.` for untrusted text.
+- Prefer declarative same-app targets. A literal external target must use HTTPS. Reject HTTP, dynamic target substitutions, `javascript:`, `data:`, protocol-relative, credential-bearing, or path-traversal URLs unless a future application-specific allowlist contract proves them.
+- SQL-backed media URL columns must be statically proven by literal or `CASE` projection results. REST media URL columns must declare `authoritative-profile-url-prefixes: [...]` in the mapped profile column's `comments.comments`; use `application-static-relative` for a relative-path-only field or list exact HTTPS prefixes.
+- REST-backed Cards reference a declared shared REST Data Source, HTTPS REST Data Source Server, and APEX Web Credential. Credentials stay in the shared credential, and `advanced.validForUrls` must include the exact resolved server plus source-path prefix.
+
+Rule ID: `CARDS_SECURITY_REQUIRED_001`.
+
+## Responsive Universal Theme Layout
+
+- Emit `componentAppearance.layout: grid` for the standard responsive layout, `float` when cards should wrap to available width, or `horizontal` when cards should stack. Choose from explicit layout intent.
+- Emit `componentAppearance.gridColumns` only with `layout: grid` and an explicit fixed count of `2`, `3`, `4`, or `5`.
+- Use `componentAppearance.cssClasses` only for a proven Cards-container class. Do not use custom CSS, row spans, or invented breakpoints to force responsiveness.
+- Use `appearance.template: @/cards-container` and exact build-pinned template option values.
+
+## Interaction Boundary
+
+- This pattern may emit a card link/action, a Cards-region refresh dynamic action, and the page items required by that refresh.
+- This pattern must not emit Faceted Search, Smart Filters, search fields, facets, filter blocks, results-region orchestration, or filter-specific dynamic actions.
+- If the request combines Cards with filtering/search, route to the Faceted Search or Smart Filters page pattern and treat Cards only as that pattern's results region. In an application UX contract, declare that filtering pattern as the page owner rather than leaving `visual-summary-cards` as the sole pattern.
+- Routing precedence: generic Cards filtering or `cards search` -> Faceted Search; direct Smart Filter Search wording -> Smart Filter Search; never co-own both.
+
+Rule ID: `CARDS_INTERACTION_BOUNDARY_REQUIRED_001`.
+
+## Verification Checklist
+
+1. The normalized intent selects `visual-summary-cards`, not Dashboard, Metric Card, or Interactive Grid by synonym alone.
+2. Source mode is exactly SQL query or REST Data Source and every requested mapping has evidence.
+3. Native title/subtitle/body, media, icon, badge, and action blocks are used before HTML fallbacks.
+4. Conditional style values are proven to return only the six allowed Universal Theme semantic tokens or `NULL` and are mapped only through `card.cssClasses`.
+5. Refresh wiring names the trigger, region static ID, and any page items to submit.
+6. Automatic responsive layout is the default; fixed columns are explicit and within `2` through `5`.
+7. No filtering/search components are emitted by this pattern.
+8. Page, region/action, target, HTML escaping, URL, and REST credential controls match the Cards security boundary.

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

@@ -161,8 +161,8 @@ Critique Gate — Navigation & Grouping (non-modal)
 - Allow a thin `type: executeCode` wrapper for packaged routines only when the block is a small named-notation package call plus direct page-item assignment required for a page-coupled loader or before-header branch-gated flow.
 - DO NOT use `type: executeCode` to re-embed business logic that belongs in the package; non-compliant wrappers must be flagged by critique (see 00-guard and 20-data/apex.logic.md).
 - This section governs page processes only. Application processes (`appProcess`) must use `type: executeCode` per 00-guard and 10-global policies.
-- Advisory threshold: if any inline PL/SQL body in page-level artifacts exceeds 4000 raw characters, critique should emit warning `PLSQL_LENGTH_WARN_001` and recommend extracting logic into `app_process_api` (or justified alternative). For processes, the preferred target shape is `type: invokeApi`, with the thin-wrapper exception used only when it is explicitly justified by runtime-safe page-item orchestration.
-- Advisory threshold: if any inline SQL body in page-level artifacts exceeds 4000 raw characters, critique should emit warning `SQL_LENGTH_WARN_001` and recommend extracting the query into a secure view that page-level artifacts reference instead of embedding inline.
+- Hard limit: if an inline PL/SQL body in a page-level artifact exceeds 4000 raw characters, critique must hard-fail `PLSQL_INLINE_BLOCK_001` and require extraction into `app_process_api` (or a justified alternative). For processes, the preferred target shape is `type: invokeApi`, with the thin-wrapper exception used only when justified by runtime-safe page-item orchestration.
+- Hard limit: if an inline SQL body in a page-level artifact exceeds 4000 raw characters, critique must hard-fail `SQL_INLINE_BLOCK_001` and require extraction into a secure view referenced by the page artifact.
 - Dynamic Content regions may use plsqlFunctionBody for rendering HTML/CLOB; they must not perform DML or manage transactions.
 
 ## Linking Patterns

package/skills/apexlang/references/policies/memory-bank/30-pages/apex.smart-filter-search.md

@@ -1,107 +1,178 @@
-## Smart Filter & Search Page Standards
+## Smart Filter Search Page Standards
 
-Rules and conventions for Oracle APEX pages that center on the Smart Filters component paired with a tabular or card-based results region.
+Canonical rules for a non-modal Oracle APEX page built around one Smart Filters region and one authoritative results region.
 
-Keywords: smart filter, smart filters, smart search, quick search, multi-attribute search
+Keywords: smart filter, smart filters, smart filter search, searchable attributes, suggestion chips, refinements
 
 ---
 
-## Purpose and Scope
-- Deliver a deterministic recipe for implementing Smart Filter & Search experiences that combine a Smart Filters region with a single authoritative results region.
-- Ensure consistency with Universal Theme defaults, guardrails defined in `00-guard`, and the component template at `templates/region-components/smart-filter-search/smart-filter-search._common.md`.
-- Apply to non-modal pages whose primary interaction is searching/list filtering rather than data entry.
+## Purpose and Authority
+
+- Use the `smart-filter-search` pattern and construction pack before loading this page standard or its template family.
+- Use compiler metadata for APEXlang legality. Ticket fields are requirements, not proof that a same-named DSL property exists.
+- Use the exact Smart Filter family contract at `templates/region-components/smart-filter-search/smart-filter-search._common.md` after the structured pack is selected.
+
+### Deterministic routing precedence
+
+- `Smart Filter Search` or `Smart Filters region` -> `smart-filter-search`; exclude `faceted-search`.
+- `Faceted Search`, `facets`, or generic filtering -> `faceted-search`.
+- `Cards` + generic filtering or `cards search` -> `faceted-search`; Cards are results only.
+- `Cards` + direct Smart Filter Search wording -> `smart-filter-search`; no co-ownership.
+
+These precedence rules are routing behavior and are covered by resolver tests; they do not authorize mixing Faceted Search and Smart Filters on one page.
 
 ---
 
-## Page Template & Navigation (Non-Negotiable)
-1. Use the Standard page template (`pageTemplate: @/standard`) unless a documented exception requires another layout. Keep `templateOptions: #DEFAULT#`.
-   Keep each value exact. `#DEFAULT#` remains standalone, and documented composites such as `t-Region--hideHeader js-addHiddenHeadingRoleDesc` remain one atomic entry.
-2. Include a Breadcrumb region using the title-bar template. Position it in `slot: REGION_POSITION_01` with `sequence: 10`.
-   - Primary page-level create actions, such as Create Product or Create Customer, belong on the breadcrumb/title-bar region, not inside the filtered report region toolbar.
-3. Follow `apex.page.md` for page naming, alias, title, breadcrumb entry, and navigation list updates.
-4. Disable form autocomplete on search-driven pages unless business requirements state otherwise.
+## Required Generation Plan
+
+Do not generate until the plan records all of the following:
+
+| Decision | Required evidence |
+|----------|-------------------|
+| `base_region_static_id` | One exact, page-unique results-region static id. |
+| `base_source` | Secured view or canonical SQL plus `object_evidence_source: schema_doc | live_db | user_asserted`. |
+| `searchable_attributes` | Explicit non-empty allowlist proven in the base projection. |
+| `match_semantics` | One of `contains`, `starts`, or `exact`, plus supported per-attribute overrides if any. |
+| `min_chars` / `max_len` | Positive integers with `max_len >= min_chars`. |
+| `tokenization_policy` | Frozen trimming, whitespace, punctuation, case/accent, and token-order behavior. |
+| `settings_contract` | Requested values and property-level compiler evidence for the target build. |
+| `security_scope` | Effective authorization and server-side condition for the Smart Filters region, base region, suggestions, and refinements. |
+| `performance_readiness` | Index/search strategy, statistics status, and expected cardinality. |
+
+Stop with Missing Inputs while any required decision or evidence source is unresolved.
+
+Persist the structured plan as JSON beside the app (for auto-discovery) or pass it through the generation gate. Keep ordinary `apexlang validate --app-path <path>` flag-free; use `--require-smart-filter-generation-plan` only at a mandatory generation gate. A plan may contain one direct page object or a `pages` array keyed by page number.
+
+Validation layers:
+
+- `artifact`: topology, target type/order, source mode/projection, wildcard rejection, allowlist order, scope inheritance, refinement shape, compiler-supported settings.
+- `plan`: object evidence, `no_rewrite`, match/length/tokenization/compiler evidence, index strategy, statistics, cardinality.
+- `runtime`: focus/announcement behavior, no-reload refresh, filtered exports under active scope.
+
+Templates and ticket prose are not evidence for `plan` or `runtime`.
 
 ---
 
-## Core Composition (Top → Bottom)
-1. **Breadcrumb / Header** – Optional wrapper region for breadcrumbs and page-level actions.
-2. **Smart Filters Region** – Region type `smartFilters`, parented to the breadcrumb/header region when using the PLUGIN_SEARCH slot, otherwise place in BODY with `sequence: 10`.
-3. **Results Region** – Classic Report (preferred), approved alternative (Cards, Interactive Report/Grid), or a companion report/cards region for map pages.
-4. **Optional Export / Download** – When exports are enabled, expose them via the results region (e.g., PDF download button) rather than standalone buttons.
+## Page Composition
+
+1. Use the Standard page template unless a higher-precedence page contract proves another layout.
+2. Place page-level navigation and create actions in the breadcrumb/title-bar region when present.
+3. Declare exactly one Smart Filters region before exactly one authoritative base results region.
+4. Bind `source.filteredRegion` to `@<base_region_static_id>` and to no other region.
+5. Keep optional maps/charts as sibling visualizations; they are not additional Smart Filter base regions.
+6. Keep keyboard order from page guidance to Smart Filters to results.
 
-Maintain the page grid so that Smart Filters sits visually above or beside the results region while respecting UT responsive behavior.
+The APEX 24.2 base-region allowlist is Classic Report, Cards, Map, and Calendar. Interactive Report, Interactive Grid, and Content Row are not supported by this pinned contract. See [Oracle APEX 24.2 Smart Filters](https://docs.oracle.com/en/database/oracle/apex/24.2/htmdb/creating-smart-filters-page-manually.html). Target the Map region static id, not a layer; this single-dataset contract requires exactly one Map layer with a provable source. Additional visualizations may remain siblings. Preserved Markdown syntax examples from other compiler releases are not APEX 24.2 compatibility evidence; the pinned allowlist is enforced on generated `.apx` artifacts.
 
 ---
 
-## Smart Filters Configuration (Non-Negotiable)
-1. `filteredRegion` must point to the static ID of the results region.
-   The filtered target must be the page's actual report/cards-style results region. Do not target map regions or map layers directly; on map pages, target the companion result region and refresh the sibling map explicitly.
-   Declare the Smart Filters region before the referenced results region in the page file.
-2. Preserve `templateOptions: #DEFAULT#` unless a documented template-option exception exists. Do not invent classes.
-3. Emit optional Smart Filters settings only when compiler metadata for the active build proves the property is valid.
-4. Order filters: primary search first, then categorical filters (checkbox/radio), then range or other specialty filters.
-5. Use `suggestions.type: dynamic` for facet filters unless a static list is mandated.
-6. Provide semantic labels and placeholders; if the Smart Filters region is the primary search control, set `accessibility.landmarkType: search`.
-
-### Filter Types
-- **Search Filter** – Consolidate free-text search across key columns via the canonical `source.dbColumns` list. Do not collapse the search filter into a single-column shortcut shape or other undocumented source variant.
-- **Categorical Filters** – Prefer checkbox group or radio group facets with `lov.type: distinctValues` for table-backed columns. Provide `listEntries.zeroCountEntries: disable` to hide empty facets.
-- **LOV Source** – For demo/sample data, distinct values are acceptable; for production, use curated LOVs or SQL views to control display order.
+## Base Region and Source Contract
+
+- The page has exactly one base region for search, suggestions, refinements, and result count semantics.
+- `base_region_static_id` is mandatory and must resolve to that region's exact static id.
+- The base source is a secured view or supplied canonical SQL. Prove all objects and projected columns before generation.
+- Record named `base_source.object_evidence` entries with `object` and `source` (`schema_doc`, `live_db`, or `user_asserted`) matching every emitted source object. Booleans, bare evidence labels, and unrelated object names do not qualify.
+- For `secured_view`, the entry matching `tableName` must additionally declare `object_type: view` and `secured: true`; a `tableView` source or a column dictionary alone does not prove a secured view.
+- For `canonical_sql`, store the supplied SQL in `base_source.canonical_sql`. Validation compares it to the emitted SQL unchanged, apart from outer whitespace. The local object-scope checker supports simple SELECTs, joins, subqueries, and named function calls; CTEs, database links, and opaque table functions stop with Missing Inputs until their object scope can be proven.
+- Do not auto-modify, widen, wrap, or inject predicates into canonical SQL to satisfy Smart Filter requirements.
+- Do not use `select *`; keep the projection explicit so searchable and display columns can be proven.
+- Preserve bind variables and the security predicates owned by the supplied source.
+- Results-region pagination, download, no-data messaging, and column presentation remain owned by the selected exact results-region contract.
+- `SMART_FILTER_BASE_SOURCE_CONTRACT_REQUIRED_001` blocks generation unless the source mode, object evidence, explicit projection, and no-rewrite decision are recorded.
 
 ---
 
-## Results Region Requirements
-1. **Classic Report Defaults**
-   - `appearance.template: @/standard`
-   - `appearance.templateOptions: [ #DEFAULT#, t-Region--noPadding, t-Region--hideHeader js-addHiddenHeadingRoleDesc, t-Region--scrollBody ]` when scrollable body is desired.
-   - `componentAppearance.template: @/standard` with stretch/static row color options as needed.
-2. Include `messages.whenNoDataFound` with user-friendly copy (e.g., `no data found`).
-3. Default pagination for a Classic Report results region is `rowRangesXToYNoPagination`. Switch to another catalog option (see `20-data/apex.sql.md`) only when the user asks for paging controls or when dataset volume requires them.
-4. Apply end alignment to numeric columns and hide surrogate keys with `type: hidden`.
-5. When exports are required, enable them via the region’s Download attributes instead of custom buttons; respect security guardrails for file generation.
-
-### Alternative Result Types
-- Cards: follow card policies from `apex.dashboard.md` and the Cards policy section.
-- Interactive Report/Grid: ensure all controlling filters are listed in `pageItemsToSubmit` and the IR/IG configuration follows its respective memory-bank rule.
-- Content Row / Metric Card: allowed only when the page still has one authoritative row-based results region with compatible filterable source columns.
-
-### Map + Filter Pages
-- Smart Filters must target an authoritative report/cards region on map pages.
-- Keep sibling maps synchronized with explicit refresh behavior after Smart Filter changes. Do not target the map directly and do not add unsupported map-layer `source.pageItemsToSubmit` to force the filter state into the layer.
+## Searchable Attributes and Filter Children
+
+- Emit at least one `type: search` child using `source.dbColumns`.
+- Populate `source.dbColumns` only from the ordered `searchable_attributes` allowlist. Never infer the allowlist from every projected column.
+- Every allowlisted attribute must exist in the security-trimmed base projection. Hidden, sensitive, tenant-key, and authorization-control columns are not searchable unless explicitly approved.
+- Order the primary search child before categorical and range refinements.
+- Use page-scoped filter tokens such as `P{page}_F_SEARCH`; avoid generic or colliding names.
+- Categorical/range LOVs and values must be subsets of the same base dataset and must follow the compiler-valid child shape.
 
 ---
 
-## Optional Header Actions
-- Primary/secondary buttons should live in the header region slots (`PLUGIN_PRIMARY_ACTIONS`, `PLUGIN_SECONDARY_ACTIONS`).
-- Use shared button templates (`@/button`) with `templateOptions: #DEFAULT#`. Keep action layout within template and slot defaults; do not add ad hoc classes.
-- Actions must be wired via dynamic actions or navigation that respects checksum policies.
+## Search Semantics and Tokenization
+
+- Record one default semantic: `contains`, `starts`, or `exact`. Do not leave matching behavior implicit.
+- `contains` matches a normalized token within a value; `starts` matches when the normalized value starts with the token; `exact` matches the complete normalized value.
+- Do not execute searches or suggestions below `min_chars`.
+- Reject input above `max_len` predictably; do not silently mutate it in SQL.
+- Apply the same frozen tokenization policy to search, suggestions, and refinements. Define trimming, repeated whitespace, punctuation boundaries, case normalization, accent normalization, duplicate tokens, and token order.
+- Use bind values for user input. Never concatenate search text into SQL.
+- `SMART_FILTER_SEARCH_BEHAVIOR_CONTRACT_REQUIRED_001` blocks generation unless exactly one semantic, positive integer bounds with `max_len >= min_chars`, every tokenization decision, and property-level compiler evidence are recorded.
+- If the active compiler cannot represent a required behavior, stop with Missing Inputs instead of inventing a property or rewriting the base source.
 
 ---
 
-## Data, Performance & Sample Data
-- Keep Smart Filter results backed by performant SQL (views or packaged APIs per `20-data/apex.sql.md`).
-- For normal report/card targets, leverage `filteredRegion` so APEX handles predicate composition. For sibling maps, use an explicit refresh pattern backed by live-valid map metadata for the active compiler.
-- Demo/skeleton pages may use `sampleData` sources (e.g., `employees`); production pages must point to actual schema objects.
+## Compiler-Gated UI Settings
+
+The required UI contract is:
+
+- `maxSuggestionChips: 100`
+- `moreFiltersSuggestionChip: true`
+- `compactNosThreshold: 10000`
+- `showTotalRowCount`: explicitly `true` or `false`
+- `totalRowCountLabel: Results` when `showTotalRowCount` is `true`; omit it when false
+
+For each property, record the target compiler build and active-property evidence. Emit only properties exposed by that compiler. `SMART_FILTER_SETTINGS_VALUE_REQUIRED_001` enforces the values above for every supported property, including the conditional count label. Missing evidence raises `SMART_FILTER_SETTINGS_COMPILER_EVIDENCE_REQUIRED_001`; unsupported properties raise `SMART_FILTER_SETTINGS_UNSUPPORTED_001` and remain unresolved until the target build or an approved alternative satisfies the requirement. Never silently discard requested values.
+
+---
+
+## Security and Data-Leakage Contract
+
+- The Smart Filters and base regions must share the same effective authorization scheme and server-side condition.
+- Apply the same checks recursively to `filterGroup` containers and their `checkbox` children. Groups inherit scope from their parent, and children inherit from the group. Validate group suggestion sources even when the group has no source column; validate every child column against the base projection.
+- Both may omit authorization/condition only when the page contract explicitly permits the same public scope for both.
+- Suggestion chips, suggestions, refinement values, counts, and result rows must derive from the same security-trimmed base dataset.
+- Do not query a broader table for convenience, bypass a secured view, or omit tenant/row-level predicates in suggestion/refinement sources.
+- Treat a suggestion value or count visible outside the base security scope as a data leak and a merge blocker.
 
 ---
 
-## Accessibility & UX
-- Ensure every filter has a concise label; avoid abbreviations unless registered in `apex.acronyms.md`.
-- Provide accessible text for export links and total count indicators through the filtered results region. Do not emit Smart Filters `settings.showTotalRowCount` for APEX 26.1 unless compiler metadata for the active build proves that property exists.
-- Maintain consistent sequencing so keyboard navigation progresses from filters into results.
+## Performance Readiness
+
+- Record expected base cardinality and the data-volume assumption used for UX and query decisions.
+- Confirm optimizer statistics status for the base objects and relevant indexes.
+- Record an index/search strategy for every searchable attribute and selected semantic.
+- Do not claim that a normal B-tree index optimizes substring `contains` behavior. Prove a compatible text/function-based strategy or record the accepted scan cost.
+- `SMART_FILTER_PERFORMANCE_READINESS_REQUIRED_001` blocks readiness while index strategy, statistics status, or expected-cardinality evidence is missing.
+- Avoid applying functions to indexed searchable columns unless matching function-based index evidence exists.
+- Do not mark the implementation ready while index strategy, statistics status, or expected cardinality is unresolved.
+- The validator rejects duplicate `source.dbColumns` entries and, when a Generation Plan is supplied, requires the emitted order to equal the declared ordered allowlist.
 
 ---
 
-## Testing & Validation Checklist
-- Smart Filters refreshes results region without page reload.
-- Filters display only relevant values (no orphan facets with zero results).
-- Download/export actions honor current filters.
-- Breadcrumb and navigation entries route to the correct page with checksum protection.
+## Accessibility and UX
+
+- Give every search/refinement child a concise visible label and useful help when behavior is not self-evident.
+- Use the search landmark when compiler truth supports the selected Smart Filters accessibility shape.
+- Keep total-count labeling consistent: `Results` only when total row count is shown.
+- Preserve visible focus order and announce result changes through supported native region behavior.
+- Add help/comments to every search and refinement child. Record compiler-supported landmark/focus behavior in the plan; do not invent accessibility properties.
 
 ---
 
-## References & Assets
-- Template: `templates/region-components/smart-filter-search/smart-filter-search._common.md`
-- Example page: `applications/apexlang-skeleton-test-application101/pages/p00010-smart-filter-search.apx`
-- Oracle APEX Smart Filters documentation
-- Pair with related rules: `apex.dashboard.md` (filters section) and `apex.faceted-search.md` for alternate filtering patterns.
+## Validation Checklist
+
+- Exactly one Smart Filters region targets exactly one existing base region and appears before it.
+- `base_region_static_id` matches the target static id.
+- Base source and every searchable attribute have accepted object evidence.
+- `source.dbColumns` equals the explicit allowlist and contains no extra column.
+- Match semantics, `min_chars`, `max_len`, and tokenization are explicit and consistent.
+- Every requested setting has property-level compiler evidence and the required value.
+- Authorization, server-side conditions, suggestions, refinements, counts, and results share one effective security scope.
+- Index strategy, statistics status, and expected cardinality are recorded.
+- Search refreshes results without page reload and exports honor the active filters.
+- Runtime acceptance records both result refresh without page reload and filtered export behavior.
+
+---
+
+## References
+
+- Structured contracts: `assets/contracts/page-patterns.json`, `assets/contracts/page-construction-packs.json`
+- Template family: `templates/region-components/smart-filter-search/`
+- Cross-region constraints: `references/policies/memory-bank/40-components/apex.region-interactions.md`
+- SQL and evidence rules: `references/policies/memory-bank/20-data/apex.sql.md`, `references/policies/memory-bank/00-guard/ai.guard.md`
+- Alternative filtering pattern: `references/policies/memory-bank/30-pages/apex.faceted-search.md`

package/skills/apexlang/references/policies/memory-bank/40-components/apex.region-interactions.md

@@ -4,9 +4,13 @@
 Defines reusable APEXlang region interaction contracts for links, actions, filters, contextual regions, parent-child layout, and comments.
 
 ## Interaction and Action Constraints
-- Metric Card and Chart regions do not own links or actions; use adjacent cards, reports, buttons, or list entries for navigation.
+- Chart regions do not own links or actions; use adjacent cards, reports, buttons, or list entries for navigation.
+- Metric Card supports one row-level action position, `link`. Use a declarative behavior target, deterministic action sequence, projected row mappings, and no action template or label.
+- Metric Card `redirectThisApp` and `redirectOtherApp` link behaviors require `target`; `redirectUrl` requires a reviewed safe `targetUrl`; `triggerAction` emits neither target property and requires a matching event consumer. Reject dangerous URL schemes, protocol-relative or wholly dynamic destinations, substitutions outside query parameters, inline handlers, URL overrides in `linkAttributes`, and unsafe new-window attributes. The URL scheme, host, path, and fragment must remain static.
+- Metric Card grouping requires grouped child-column metadata plus deterministic static ordering; native single/multiple selection requires correctly typed same-page selection items and a primary-key child column.
 - Cards `fullCard` links must not emit a label; Cards `button` links must emit a concise label.
-- Native Cards actions are row navigation actions using `label` plus declarative `behavior.target`; do not emit `position` or attach processes directly to Cards actions.
+- Native Cards actions are row navigation or decision actions using explicit `layout.sequence`; `button` actions use `label`, `layout.position`, and optional native `appearance`, while full-card/title/subtitle/media actions omit button-only fields. Use declarative `behavior.target` for redirects, and use a nested `triggerAction` child only with `behavior.type: triggerAction`, omitting navigation targets.
+- When full-card navigation and a decision button coexist, document the intended precedence and evidence-backed conditions in the UX contract. Do not infer mutually exclusive business conditions from the action set.
 - List regions are navigation-only; they bind to shared list entries and must not emit data sources, filters, hidden page items, columns, links, or actions.
 - Management and launcher hub shared list entries should include `icon.imageIconCssClasses` with a conservative `fa-*` token and `userDefinedAttributes { 1: ... }` description text so media-list hubs render as scannable launch cards.
 - Report drilldown should be modeled as report/column links or region-level links, not as unsupported report actions.
@@ -16,6 +20,9 @@ Defines reusable APEXlang region interaction contracts for links, actions, filte
 - Filter item names are page item tokens, not labels. Derive them from page number and database column: `P{page}_F_{UPPER_DB_COLUMN}`.
 - Range filters use the same single canonical filter name as the database column; do not create `_FROM` and `_TO` item pairs for one range filter.
 - Smart Filters search item token defaults to `P{page}_F_SEARCH`; avoid legacy `P{page}_SEARCH` for generated search items.
+- A Smart Filters region must bind to exactly one APEX 24.2 Classic Report, Cards, Map, or Calendar base region through its explicit static id; sibling visualizations are not additional filter targets.
+- Smart Filter search, suggestion, refinement, and count behavior must stay within the base region's effective authorization, server-side condition, and security-trimmed dataset.
+- Treat `source.dbColumns` as an explicit searchable-attribute allowlist, not as permission to expose every base projection column.
 - Filter item names must not collide with same-page hidden items or form page item names; suffix deterministically only when there is a real collision.
 
 ## Contextual and Parent-Child Layout

package/skills/apexlang/references/policies/memory-bank/40-components/apex.region-media.md

@@ -11,12 +11,13 @@ Defines reusable APEXlang BLOB, file/image, storage companion, and visual-token
 - SQL-backed Classic Report and Interactive Report BLOB display aliases must project `dbms_lob.getlength(<blob_expr>)`; Cards and Content Row must project the raw BLOB expression for display-image aliases.
 - Raw LOB projection is display-only. Do not sort, group, distinct, join, analytically partition/order, or compare raw LOB aliases; follow `SQL_PLSQL_LOB_COMPARISON_KEY_FORBIDDEN_001` in `20-data/apex.sql.md`.
 - Cards image display uses the native Cards media block, not report-style child columns.
-- Cards BLOB display uses `media { source: blobColumn blobColumn: <BLOB_COLUMN_ALIAS> }`.
-- Cards URL-column display uses `media { source: urlColumn urlColumn: <URL_COLUMN_ALIAS> }`.
-- Cards direct URL display uses `media { source: imageUrl url: <STATIC_IMAGE_URL_OR_COLUMN_SUBSTITUTION> }`; `url` may be a static URL or an APEX substitution such as `&IMAGE_URL_COLUMN.`.
+- Cards BLOB display uses `media { advancedFormatting: false source: blobColumn blobColumn: <BLOB_COLUMN_ALIAS> position: first sizing: cover }`.
+- Cards URL-column display uses `media { advancedFormatting: false source: urlColumn urlColumn: <URL_COLUMN_ALIAS> position: first sizing: cover }`.
+- Cards direct URL display uses `media { advancedFormatting: false source: imageUrl url: <STATIC_IMAGE_URL_OR_COLUMN_SUBSTITUTION> position: first sizing: cover }`; `url` may be a static URL or an APEX substitution such as `&IMAGE_URL_COLUMN.`.
 - Cards BLOB metadata uses `blobAttributes { mimeTypeColumn: <MIME_TYPE_ALIAS> lastUpdatedColumn: <LAST_UPDATED_ALIAS> }`, and that block is valid only when `media.source: blobColumn` is present.
-- Cards media presentation defaults are represented by omission; do not emit APEXlang-side `position`, `appearance`, or `sizing` for default Cards media.
-- Cards media presentation properties are valid optional controls only for explicit non-default requirements: `position: first | background`, `appearance: square | widescreen`, and `sizing: cover`. Never emit `position: first`, `appearance: square`, or `sizing: cover` just to mirror APEX defaults.
+- Native Cards media requires `advancedFormatting`, `position`, and, when `source` is set, `sizing`. Use deterministic defaults `advancedFormatting: false`, `position: first`, and `sizing: cover`.
+- Supported presentation values are `position: first | body | background`, optional `appearance: square | widescreen`, and `sizing: fit | cover`.
+- Map accessible image text with `media.imageDescription`; `accessibleDescription` is not a Cards media property in the APEX 26.1 grammar.
 - Cards regions with BLOB media must define `card.primaryKeyColumn1` and keep companion image metadata columns projected in SQL when available, but must not invent additional `media` or `blobAttributes` properties.
 - `Storage -> File Types` is Form-only for upload render roles and must be a comma-separated MIME-type list; `File Name Column` must be normalized to `Filename Column`.
 - `Alt Text Column` applies only to image upload/display flows and must not be used for plain file upload.

package/skills/apexlang/references/policies/memory-bank/systemPatterns.md

@@ -27,7 +27,13 @@
 - `skills/`
   - Direct-entrypoint skills, domain skills, agents, references, and assets.
 - `templates/`
-  - Canonical template families and scenario docs.
+  - Canonical exact-match example families and renderer reference docs. Templates are not the primary syntax oracle.
+- APEXlang grammar asset
+  - Syntax oracle for generated DSL shape.
+- Compiler prop-map tools
+  - Compiler-backed semantic oracle for property, enum, slot, template-option, and component-variant legality.
+- APEXlang structured contracts
+  - Compact pattern, IR, and package-layer contracts used before broad Markdown loading.
 - `applications/app_###/`
   - Final output root for generated application artifacts.
 - `artifacts/`
@@ -42,8 +48,10 @@
 
 ## Deterministic Routing
 - Natural-language routing relies on:
+  - `assets/rules.catalog.json`
   - `assets/apex-generation/components.registry.json`
   - `assets/rules-mapping.json`
+- Non-trivial routing should produce a compact trace from normalized intent to rule/contract, grammar/compiler evidence, and exact template path only when needed.
 - Direct-entrypoint skills that support one-message invocation should expose a `Router Contract` section in `SKILL.md`.
 - Secondary reference docs must not redefine router behavior; they should point back to the owning skill.