@cspeach/cli 0.7.0 → 0.8.0

package/README.md

@@ -60,6 +60,32 @@ machine.
 Ten Forge Rules are non-negotiable. Full philosophy in the `CSPeach Principles`
 preamble shown to the model every turn.
 
+## Cost transparency (since 0.7.0)
+
+Every turn shows what it cost. After each model call you see:
+
+```
+session abc123 │ S4H │ /abap-explain │ 2 turns │ 487 tok │ $0.07 │ session: $0.18 │ 3.6s
+```
+
+- `tok` = tokens billed this turn (input + output + cache)
+- `$` = this turn's cost
+- `session:` = cumulative across the open session
+- `/cost` shows a per-skill / per-tool breakdown
+- `/compact` summarises older turns when context gets large (cuts subsequent-turn cost ~80-90%)
+- `auto_compact` in `~/.cspeach/config.toml` fires `/compact` automatically over a configurable threshold
+
+On `/exit` you get a session summary + the `cspeach --resume <id>` command in plain text so you can pick up where you left off.
+
+## UI modes
+
+Two REPL modes, both supported. **Default is `classic`.** Switch with `/ui ink` or `/ui classic`; saves to `~/.cspeach/config.toml` under `[ui]`.
+
+- **`classic`** — chalk + readline. The supported, demo-tested mode. Use this unless you have a reason not to. Native terminal scroll, mouse wheel, search — everything your terminal does naturally just works.
+- **`ink`** — React-based TUI. **PREVIEW.** Some rendering quirks remain (occasional phantom cursor, picker fossil in scrollback). Functional for daily use but not yet polished enough to recommend as default. Promoted to default in a later release.
+
+If `ink` is misbehaving for you, run `/ui classic` once — change applies after relaunch.
+
 ## Configuration
 
 `~/.cspeach/config.toml` is created on first `cspeach config add-sap`:

package/bench/README.md

@@ -0,0 +1,78 @@
+# Model bench
+
+Side-by-side outputs from Opus, Sonnet, and Haiku on the same ABAP prompt so
+you can decide per-skill which model carries the load before changing any
+default.
+
+## Run
+
+```bash
+pnpm bench:models
+pnpm bench:models --prompt abap-explain-bdef-handler
+pnpm bench:models --models claude-opus-4-7,claude-sonnet-4-6
+```
+
+Routes through whichever LLM mode `cspeach config` is in — managed (proxy),
+BYOK, AI Hub, or local. In managed mode the proxy injects the **real skill
+body from KV** as the system prompt, so each bench call is end-to-end
+identical to what a real `/abap-explain` invocation would do — just on a
+different model.
+
+## Prompts
+
+Drop new prompts in `prompts/<name>.md`. Format:
+
+```markdown
+---
+skill: abap-explain          # required — must be a real CSPeach skill name
+description: short label
+---
+
+## user
+[the user-side prompt the model receives]
+```
+
+Optionally include a `## system` section — it's **only** used in non-managed
+modes (BYOK, AI Hub, local) where there's no proxy to inject a skill body.
+In managed mode `## system` is ignored.
+
+## Results
+
+`results/<prompt-name>/<model>.md` — full assistant text plus latency, tokens,
+and a USD estimate (using the same pricing table the cost footer uses).
+
+Read both files side by side. If Sonnet looks like a write-off on a given
+skill, keep the skill on Opus. If it looks "as good or better," that skill
+graduates down on the next config refactor.
+
+## Cost note
+
+Each prompt × model call is one full skill turn through the proxy. The proxy
+loads the full skill body as system prompt, so input is in the 5-15k token
+range. A full 3-prompt × 3-model bench is roughly $0.30–$0.80 depending on
+output verbosity. (Haiku columns will be much cheaper than Opus.)
+
+## Verdict log
+
+Findings from each bench run, oldest first. Each entry should name the run
+date, the prompts that were benched, and the model decision per skill — so
+the config refactor (`resolveModelForSkill` + `[models.skills]`) can be
+driven from evidence, not guesses.
+
+### 2026-05-18 — initial 3-prompt run
+
+Prompts: `abap-explain-bdef-handler`, `abap-document-cds`, `abap-test-method`.
+
+| Skill | Sonnet 4.6 | Haiku 4.5 | Decision |
+|---|---|---|---|
+| `abap-explain`  | matches Opus, catches `IN LOCAL MODE` non-retrigger nuance | typo `cl_abap_behav_handler` (wrong class name) | **Sonnet OK; Haiku unsafe** |
+| `abap-document` | matches Opus + adds client-handling + `@VDM.viewType` value | invented `DSOD` authority object; misread fuzzinessThreshold direction | **Sonnet OK; Haiku unsafe** |
+| `abap-test`     | comparable rigor; asserts exception **textid** (Opus only `assert_bound`) | clean code; coverage-estimate prose shaky | **Sonnet OK; Haiku borderline** |
+
+Pattern: SAP/ABAP corpus is thinner than Python/JS — Haiku hallucinates SAP
+terms on multi-paragraph synthesis. Sonnet does not. Do NOT route any
+ABAP-content skill to Haiku based on this evidence.
+
+Skills NOT yet benched (kept on Opus by default): `abap-generate`, `-rap`,
+`-modernize`, `-design`, `-refactor`, `-review`, `-cca`, anything else
+producing new code or architectural decisions. Bench before routing.

package/bench/prompts/abap-document-cds.md

@@ -0,0 +1,44 @@
+---
+skill: abap-document
+description: Document a CDS interface view with associations + currency annotation
+---
+
+## user
+
+Please document this CDS view:
+
+```cds
+@AccessControl.authorizationCheck: #CHECK
+@EndUserText.label: 'Sales Order — Interface View'
+@Search.searchable: true
+define view entity ZI_SalesOrder
+  as select from zsales_order as Header
+
+  association [0..1] to ZI_Customer       as _Customer       on $projection.CustomerID = _Customer.CustomerID
+  association [0..*] to ZI_SalesOrderItem as _SalesOrderItem on $projection.SalesOrderID = _SalesOrderItem.SalesOrderID
+  association [0..1] to I_Currency        as _Currency       on $projection.CurrencyCode = _Currency.Currency
+
+{
+  key Header.sales_order_id        as SalesOrderID,
+      Header.customer_id           as CustomerID,
+      Header.order_date            as OrderDate,
+
+      @Search.defaultSearchElement: true
+      @Search.fuzzinessThreshold: 0.8
+      @ObjectModel.text.element: [ '_Customer.CustomerName' ]
+      Header.customer_id           as CustomerIDForSearch,
+
+      @Semantics.amount.currencyCode: 'CurrencyCode'
+      Header.net_amount            as NetAmount,
+      Header.currency_code         as CurrencyCode,
+
+      Header.created_at            as CreatedAt,
+      Header.created_by            as CreatedBy,
+      Header.last_changed_at       as LastChangedAt,
+      Header.last_changed_by       as LastChangedBy,
+
+      _Customer,
+      _SalesOrderItem,
+      _Currency
+}
+```

package/bench/prompts/abap-explain-bdef-handler.md

@@ -0,0 +1,57 @@
+---
+skill: abap-explain
+description: Explain a managed RAP behavior pool with a validation + determination
+---
+
+## user
+
+Please explain this behavior pool:
+
+```abap
+CLASS lhc_salesorder DEFINITION INHERITING FROM cl_abap_behavior_handler.
+  PRIVATE SECTION.
+    METHODS validateorderdate FOR VALIDATE ON SAVE
+      IMPORTING keys FOR SalesOrder~validateorderdate.
+    METHODS determinenetamount FOR DETERMINE ON MODIFY
+      IMPORTING keys FOR SalesOrder~determinenetamount.
+ENDCLASS.
+
+CLASS lhc_salesorder IMPLEMENTATION.
+  METHOD validateorderdate.
+    READ ENTITIES OF zr_salesorder IN LOCAL MODE
+      ENTITY SalesOrder FIELDS ( OrderDate ) WITH CORRESPONDING #( keys )
+      RESULT DATA(lt_orders).
+
+    LOOP AT lt_orders INTO DATA(ls_order).
+      IF ls_order-OrderDate < cl_abap_context_info=>get_system_date( ).
+        APPEND VALUE #( %tky = ls_order-%tky ) TO failed-salesorder.
+        APPEND VALUE #(
+          %tky = ls_order-%tky
+          %msg = new_message_with_text(
+                   severity = if_abap_behv_message=>severity-error
+                   text     = 'Order date must be today or in the future' )
+        ) TO reported-salesorder.
+      ENDIF.
+    ENDLOOP.
+  ENDMETHOD.
+
+  METHOD determinenetamount.
+    READ ENTITIES OF zr_salesorder IN LOCAL MODE
+      ENTITY SalesOrder FIELDS ( Quantity UnitPrice ) WITH CORRESPONDING #( keys )
+      RESULT DATA(lt_orders).
+
+    DATA lt_update TYPE TABLE FOR UPDATE zr_salesorder\\SalesOrder.
+    LOOP AT lt_orders INTO DATA(ls_order).
+      APPEND VALUE #(
+        %tky      = ls_order-%tky
+        NetAmount = ls_order-Quantity * ls_order-UnitPrice
+        %control-NetAmount = if_abap_behv=>mk-on
+      ) TO lt_update.
+    ENDLOOP.
+
+    MODIFY ENTITIES OF zr_salesorder IN LOCAL MODE
+      ENTITY SalesOrder UPDATE FIELDS ( NetAmount )
+        WITH lt_update.
+  ENDMETHOD.
+ENDCLASS.
+```

package/bench/prompts/abap-test-method.md

@@ -0,0 +1,42 @@
+---
+skill: abap-test
+description: Generate an ABAP Unit test class for a small business rule method
+---
+
+## user
+
+Please write an ABAP Unit test class for this method:
+
+```abap
+CLASS zcl_discount_calculator DEFINITION
+  PUBLIC FINAL CREATE PUBLIC.
+
+  PUBLIC SECTION.
+    "! Returns the discount percentage (0..30) for a given net amount.
+    "!   < 1000  → 0%
+    "!   < 5000  → 5%
+    "!   < 10000 → 10%
+    "!   >= 10000 → 15%
+    "! Raises zcx_discount_error on negative input.
+    METHODS calculate_discount
+      IMPORTING iv_net_amount      TYPE p LENGTH 13 DECIMALS 2
+      RETURNING VALUE(rv_discount) TYPE p LENGTH 3  DECIMALS 2
+      RAISING   zcx_discount_error.
+ENDCLASS.
+
+CLASS zcl_discount_calculator IMPLEMENTATION.
+  METHOD calculate_discount.
+    IF iv_net_amount < 0.
+      RAISE EXCEPTION TYPE zcx_discount_error
+        EXPORTING textid = zcx_discount_error=>negative_input.
+    ENDIF.
+
+    rv_discount = COND #(
+      WHEN iv_net_amount <  1000 THEN '0.00'
+      WHEN iv_net_amount <  5000 THEN '5.00'
+      WHEN iv_net_amount < 10000 THEN '10.00'
+      ELSE                            '15.00'
+    ).
+  ENDMETHOD.
+ENDCLASS.
+```

package/bench/results/abap-document-cds/claude-haiku-4-5.md

@@ -0,0 +1,189 @@
+# abap-document-cds — claude-haiku-4-5
+
+- **skill:** abap-document
+- **description:** Document a CDS interface view with associations + currency annotation
+- **latency:** 26816 ms
+- **input tokens:** 2,688
+- **output tokens:** 2,623
+- **cost:** $0.0158
+
+---
+
+# abap-document — ZI_SalesOrder
+
+## TL;DR
+
+**Headline:** Interface view for sales order header data with customer and item associations, read-only with authorization check.
+
+**Top 3 (priority order):**
+1. **Authorization enforced:** `#CHECK` mode requires `DSOD` and sales order read authority at runtime — verify user roles before consuming downstream.
+2. **Fuzzy search enabled on CustomerID:** `fuzzinessThreshold: 0.8` will match partial/misspelled customer names; test with typical fat-finger errors in UAT.
+3. **No filtering logic:** View exposes all rows from `zsales_order` table — upstream consumers must apply their own `WHERE` clauses; no automatic date range or status filtering.
+
+**Verdict:** Safe foundation view for consumption in analytics, APIs, or reporting. Confirm downstream apps implement business rule filtering (e.g., active orders only, date ranges).
+
+---
+
+## ZI_SalesOrder (CDS VIEW ENTITY)
+
+### Overview
+
+**Package:** (not yet read — see below)  
+**Type:** CDS View Entity (Interface Layer)  
+**Annotations:** Authorization check enabled, search enabled, end-user label "Sales Order — Interface View"
+
+**Summary:**  
+Exposes sales order header data from the custom table `zsales_order` with associations to customer master, line items, and SAP currency data. Designed as a read-only interface view for analytics, reporting, and API consumption.
+
+---
+
+### Purpose
+
+This view serves as the **interface layer** for sales order headers in the custom data model. It:
+
+1. **Presents domain data cleanly** — maps technical table column names (`sales_order_id`, `customer_id`) to business-readable field names (`SalesOrderID`, `CustomerID`).
+2. **Enforces authorization** — restricts read access to users with appropriate sales order query authority.
+3. **Enables semantic search** — makes customer name searchable via fuzzy matching (0.8 threshold = allow 20% typos).
+4. **Links related business entities** — connects to customer master, line items, and currency metadata via associations (no data duplication, navigation-based joins).
+5. **Supports consumption layers** — designed for downstream consumption by reporting tools, OData APIs, or analytical views.
+
+---
+
+### Interface
+
+**Key Field:**
+- `SalesOrderID` (Header.sales_order_id) — unique identifier for the sales order
+
+**Header-Level Fields:**
+
+| Field Name | Source | Type | Purpose |
+|------------|--------|------|---------|
+| SalesOrderID | Header.sales_order_id | key | Sales order unique identifier |
+| CustomerID | Header.customer_id | string | References customer master |
+| OrderDate | Header.order_date | date | Date order was placed |
+| CustomerIDForSearch | Header.customer_id | string | Fuzzy-searchable copy for customer lookup |
+| NetAmount | Header.net_amount | decimal | Order value (currency-aware via annotation) |
+| CurrencyCode | Header.currency_code | string | ISO currency code |
+| CreatedAt | Header.created_at | timestamp | Audit: creation timestamp |
+| CreatedBy | Header.created_by | user | Audit: creator user |
+| LastChangedAt | Header.last_changed_at | timestamp | Audit: last change timestamp |
+| LastChangedBy | Header.last_changed_by | user | Audit: last change user |
+
+**Associations (Navigation):**
+
+| Association | Target View | Cardinality | Join Condition | Purpose |
+|-------------|-------------|-------------|-----------------|---------|
+| `_Customer` | ZI_Customer | 0..1 | CustomerID | Navigate to customer master data |
+| `_SalesOrderItem` | ZI_SalesOrderItem | 0..* | SalesOrderID | Navigate to line items for this order |
+| `_Currency` | I_Currency (SAP standard) | 0..1 | CurrencyCode | Navigate to SAP currency details |
+
+**Authorization & Search:**
+- Authorization check: `#CHECK` — runtime check required (user must have query authority for sales order).
+- Default search element: `CustomerIDForSearch` with fuzzy matching (80% match threshold).
+- Searchable: all marked fields indexed for full-text search.
+
+---
+
+### Logic Flow
+
+**Data Origin & Transformation:**
+
+1. **Source:** Read all rows from custom table `zsales_order` (Header alias).
+2. **Projection:** Map technical columns to semantic field names:
+   - `sales_order_id` → `SalesOrderID` (key)
+   - `customer_id` → `CustomerID`
+   - `order_date` → `OrderDate`
+   - `net_amount` → `NetAmount` (with currency semantic)
+   - `currency_code` → `CurrencyCode`
+   - Audit fields (created/changed by/at) mapped as-is.
+3. **Duplicate CustomerID:** `CustomerIDForSearch` is a copy of `CustomerID` explicitly marked for full-text search (allows UI to search by customer name via the association).
+4. **Associations:** Three navigation paths added (not joins — lazy-loaded):
+   - To customer master for customer details.
+   - To line items for order composition.
+   - To SAP currency master for exchange rates, decimals, etc.
+5. **Authorization Gate:** View enforces `#CHECK` at query time — SAP will validate user authority before returning rows.
+
+**No filtering logic:** View is a "raw interface" — all rows from the source table are exposed. Upstream consumers must filter by date, status, or other business rules.
+
+---
+
+### Data Access
+
+| Table/View | Operation | Purpose |
+|------------|-----------|---------|
+| `zsales_order` (custom) | **READ** | Source table for all header fields (sales_order_id, customer_id, order_date, net_amount, currency_code, audit fields) |
+| `ZI_Customer` (custom view) | **READ** (via association) | Customer master lookup; enriches orders with customer details |
+| `ZI_SalesOrderItem` (custom view) | **READ** (via association) | Line items for the order; enables per-item navigation |
+| `I_Currency` (SAP standard) | **READ** (via association) | SAP currency master; provides conversion rates, decimal places |
+
+**No writes:** This is a read-only interface view. No INSERT, UPDATE, or DELETE allowed.
+
+---
+
+### Dependencies
+
+**Called by (Upstream Consumers):**  
+Unknown without further analysis — use `sap_usage_references` to identify (e.g., analytics views, OData services, reports using this view).
+
+**Calls (Dependencies):**
+- `zsales_order` — custom table (no option to change this view without understanding the source table schema).
+- `ZI_Customer` — custom customer interface view (ensure it is available and stable).
+- `ZI_SalesOrderItem` — custom sales order item interface view (ensure it exists).
+- `I_Currency` (SAP standard) — standard SAP currency master (no custom risk; always available post-installation).
+
+---
+
+### Authorization & Security
+
+**Authorization Check:** `#CHECK` mode  
+- When a user queries this view, SAP **enforces** a dynamic authorization check at runtime.
+- The specific check depends on SAP's authority object mapping for CDS views (typically `DSOD` → Data Source Object Definition or equivalent).
+- **Action required:** Verify that user roles define query access for this view; otherwise, queries will fail with "Authorization error."
+
+**Search & Indexing:**
+- `CustomerIDForSearch` with `fuzzinessThreshold: 0.8` allows typo-tolerant search (e.g., "APLE" matches "APPLE").
+- Useful for user-facing search UIs; may return false positives in strict filter scenarios.
+
+---
+
+### Data Model & Semantics
+
+**Semantic Annotations:**
+- `@Semantics.amount.currencyCode: 'CurrencyCode'` on `NetAmount` — tells consuming systems that this field is a currency amount and which field holds the currency code. Tools like SAP Analytics Cloud will format it correctly.
+- `@ObjectModel.text.element: [ '_Customer.CustomerName' ]` on `CustomerIDForSearch` — tells UI frameworks to display the customer **name** (not ID) when showing this field.
+
+**Searchability:**
+- View is marked `@Search.searchable: true` — all fields with `@Search.defaultSearchElement: true` are indexed.
+- Only `CustomerIDForSearch` is explicitly indexed; other fields are not full-text searchable by default.
+
+---
+
+### Notes & Considerations
+
+1. **No status filtering:** View exposes all orders regardless of status (open, closed, cancelled). If you need only active orders, add a downstream view or consuming WHERE clause.
+
+2. **Audit trail:** `CreatedBy`, `LastChangedBy`, `CreatedAt`, `LastChangedAt` are available for compliance; confirm these are populated in the source table `zsales_order`.
+
+3. **Association multiplicity:**
+   - Customer is 0..1 (every order may not have a customer — nullable FK?). Verify business rule: must a sales order always have a customer?
+   - Line items are 0..* (orders with no items are allowed). Confirm with business if this is intentional.
+   - Currency is 0..1 (may not exist in SAP currency master for custom codes). Test with unusual currency codes.
+
+4. **Search on CustomerID not CustomerName:** The view exposes `CustomerID` for search but links to `_Customer.CustomerName`. If users expect to search by customer **name**, ensure the downstream OData/UI binding is configured to search on `CustomerIDForSearch` and display `_Customer.CustomerName`.
+
+5. **No performance optimizations:** View is a simple 1:1 projection. For large `zsales_order` tables (millions of rows), consider:
+   - Adding a semantic partitioning hint in the view definition.
+   - Creating secondary indexes on frequently filtered columns (e.g., `OrderDate`, `CustomerID`).
+   - Testing query response times with large datasets.
+
+6. **Missing fields?** Confirm with business that all required order header fields are in the projection. If fields exist in `zsales_order` but not exposed here, add them or create a second view variant.
+
+---
+
+## Next Steps
+
+1. **Trace consumers:** Run `sap_usage_references` to identify which views, APIs, and reports consume this view.
+2. **Verify source table:** Run `sap_get_source` on `zsales_order` to confirm the schema matches the projection.
+3. **Check related views:** Retrieve `ZI_Customer` and `ZI_SalesOrderItem` to ensure the associations are compatible (key cardinality, join conditions).
+4. **Authorization testing:** Create a test user with appropriate authority and verify they can query this view without "Authorization failed" errors.
+5. **Search testing:** Test fuzzy search with intentional typos (e.g., customer name "ACME Corp" vs. search "ACME Crp") to confirm the 0.8 threshold behavior.

package/bench/results/abap-document-cds/claude-opus-4-7.md

@@ -0,0 +1,120 @@
+# abap-document-cds — claude-opus-4-7
+
+- **skill:** abap-document
+- **description:** Document a CDS interface view with associations + currency annotation
+- **latency:** 42479 ms
+- **input tokens:** 6
+- **output tokens:** 2,798
+- **cost:** $0.2099
+
+---
+
+## abap-document — ZI_SalesOrder (CDS Interface View)
+
+## TL;DR
+
+**Headline:** `ZI_SalesOrder` is a sales order header interface view exposing `zsales_order` with associations to customer, items, and currency, search-enabled on customer ID.
+
+**Top 3 (priority order — most important first):**
+1. **Interface view in a VDM-style layering** — naming prefix `ZI_` and associations to `ZI_Customer` / `ZI_SalesOrderItem` indicate this is the I-layer; consumption should happen via a `ZC_` view, not directly.
+2. **Search + text association configured on `CustomerIDForSearch`** — fuzzy search (threshold 0.8) with text resolved via `_Customer.CustomerName`; this field is a duplicate exposure of `customer_id` purely for search semantics.
+3. **Amount/currency reference pair (`NetAmount` ↔ `CurrencyCode`)** is correctly annotated; `_Currency` association to `I_Currency` makes this view S/4-VDM-compliant for currency handling.
+
+**Verdict:** Clean, well-annotated interface view. No code-level concerns — main thing to confirm with the team is whether a consumption view (`ZC_SalesOrder`) exists on top and whether `CustomerIDForSearch` duplication is intentional.
+
+---
+
+> ⚠️ **Note:** This documentation is based solely on the source you pasted. I did not call `sap_get_source`, `sap_object_structure`, or `sap_usage_references`, so package, author, change history, and where-used data are not included. If you want the full document with dependencies and metadata, re-run and I'll pull it from the system.
+
+## ZI_SalesOrder (DDLS — CDS View Entity)
+
+### Overview
+Package: *not retrieved* | Author: *not retrieved* | Last changed: *not retrieved*
+
+`ZI_SalesOrder` is an **interface-layer CDS view entity** over the custom sales order header table `zsales_order`. It exposes header fields, exposes associations to customer, items, and currency, and enables fuzzy search on the customer ID with the customer name surfaced as text.
+
+### Purpose
+Provide a reusable, semantically annotated interface for sales order header data following VDM (Virtual Data Model) conventions:
+
+- Acts as the **single source of truth for the sales order header** in the I-layer.
+- Wires up the **associations** that downstream consumption views, Fiori elements apps, and analytical views can navigate (customer, items, currency).
+- Enables **enterprise search** over the order's customer with name resolution.
+- Establishes **currency semantics** so amounts render correctly in UIs and analytics.
+
+It does **not** implement business logic, filtering, or authorization beyond `#CHECK` (DCL-based row-level auth, if a DCL exists for this entity).
+
+### Interface
+
+**Type:** `define view entity` (modern CDS, not legacy `define view`)
+
+**Source:** `zsales_order` (aliased as `Header`)
+
+**Key:**
+| Field | Type source | Notes |
+|---|---|---|
+| `SalesOrderID` | `Header.sales_order_id` | Primary key |
+
+**Exposed fields:**
+| Element | Source | Semantics / Annotations |
+|---|---|---|
+| `SalesOrderID` (key) | `sales_order_id` | — |
+| `CustomerID` | `customer_id` | — |
+| `OrderDate` | `order_date` | — |
+| `CustomerIDForSearch` | `customer_id` | `@Search.defaultSearchElement: true`, fuzziness 0.8, text from `_Customer.CustomerName` |
+| `NetAmount` | `net_amount` | `@Semantics.amount.currencyCode: 'CurrencyCode'` |
+| `CurrencyCode` | `currency_code` | Currency reference field |
+| `CreatedAt` | `created_at` | Admin field |
+| `CreatedBy` | `created_by` | Admin field |
+| `LastChangedAt` | `last_changed_at` | Admin field |
+| `LastChangedBy` | `last_changed_by` | Admin field |
+
+**Associations (exposed):**
+| Name | Cardinality | Target | Join condition |
+|---|---|---|---|
+| `_Customer` | `[0..1]` | `ZI_Customer` | `CustomerID = _Customer.CustomerID` |
+| `_SalesOrderItem` | `[0..*]` | `ZI_SalesOrderItem` | `SalesOrderID = _SalesOrderItem.SalesOrderID` |
+| `_Currency` | `[0..1]` | `I_Currency` (SAP standard) | `CurrencyCode = _Currency.Currency` |
+
+**View-level annotations:**
+- `@AccessControl.authorizationCheck: #CHECK` — DCL authorization is checked at runtime if a DCL is defined; otherwise warnings issued.
+- `@EndUserText.label: 'Sales Order — Interface View'`
+- `@Search.searchable: true` — view participates in enterprise search.
+
+### Logic Flow
+
+There is no procedural logic — this is a projection view. At runtime:
+
+1. **Select** header rows from `zsales_order`.
+2. **Apply DCL** (`#CHECK`) if a corresponding DCL role exists on `ZI_SalesOrder`.
+3. **Expose** the renamed fields and forward the three associations to consumers.
+4. On association navigation, the database joins to `ZI_Customer`, `ZI_SalesOrderItem`, or `I_Currency` as needed.
+5. For search queries, `CustomerIDForSearch` is the entry point; the engine performs fuzzy matching (threshold 0.8) and shows `_Customer.CustomerName` as descriptive text.
+
+### Data Access
+| Table/View | Operation | Purpose |
+|---|---|---|
+| `zsales_order` | READ | Source table — header data |
+| `ZI_Customer` (via `_Customer`) | READ on navigation | Customer master for text and details |
+| `ZI_SalesOrderItem` (via `_SalesOrderItem`) | READ on navigation | Child items |
+| `I_Currency` (via `_Currency`) | READ on navigation | Standard currency master (TCURC) |
+
+### Dependencies
+
+*Where-used not retrieved — re-run with system access to populate.*
+
+**Calls (compile-time dependencies):**
+- Source table: `zsales_order`
+- Associated views: `ZI_Customer`, `ZI_SalesOrderItem`, `I_Currency`
+
+**Called by:** *unknown — typically a `ZC_SalesOrder` consumption view, OData service bindings, or analytical views; confirm via `sap_usage_references`.*
+
+### Error Handling
+None at view level. Authorization failures via DCL would result in rows being filtered out, not exceptions. If `zsales_order` or any associated view is inactive or missing, the view itself will not activate.
+
+### Notes / Observations
+- **`CustomerIDForSearch` duplicates `CustomerID`** — this is a common pattern to keep `CustomerID` "clean" (no search annotations) while a separate element carries the search semantics. Confirm this is intentional and not legacy.
+- **`@AccessControl.authorizationCheck: #CHECK`** requires a DCL role (`define role` on `ZI_SalesOrder`) to actually enforce anything. Verify a DCL exists; otherwise this is effectively `#NOT_REQUIRED` with an activation warning.
+- **VDM naming** (`ZI_` prefix) suggests this is part of a layered model. Best practice: do not consume this view directly from UIs — build a `ZC_SalesOrder` on top.
+- **`I_Currency`** is the SAP-standard currency interface view; the association is correctly modeled for S/4HANA-style currency reference.
+- **No `@Metadata.allowExtensions` annotation** — if extension is expected (CDS view extensions for customer fields), add `@Metadata.allowExtensions: true`.
+- **Purpose of `CustomerIDForSearch`** is clear from annotations, but the broader business process (order-to-cash? B2B sales?) **is not derivable from the source** — confirm with the business team.