cabloy 5.1.61 → 5.1.62

package/cabloy-docs/fullstack/backend-metadata-to-frontend-table-actions-debug-checklist.md

@@ -0,0 +1,245 @@
+# Backend Metadata to Frontend Table Actions Debug Checklist
+
+This page is a symptom-first verify/debug companion for one narrow fullstack question:
+
+> when a visible Student row action is wrong, stale, hidden, or missing, which layer should I check next?
+
+Use this page together with:
+
+- [Backend Metadata to Frontend Table Actions](/fullstack/backend-metadata-to-frontend-table-actions)
+- [Backend Metadata to Frontend Table Actions Source Reading Map](/fullstack/backend-metadata-to-frontend-table-actions-source-reading-map)
+- [Contract Loop Playbook](/fullstack/contract-loop-playbook)
+- [Table Action Visibility and Permission Flow Guide](/frontend/table-action-visibility-permission-flow-guide)
+- [Zova Table Source Reading Map](/frontend/zova-table-source-reading-map)
+
+> [!TIP]
+> **Mixed-chain diagnosis path**
+>
+> 1. **[Backend Metadata to Frontend Table Actions](/fullstack/backend-metadata-to-frontend-table-actions)** — understand the mixed chain conceptually
+> 2. **[Backend Metadata to Frontend Table Actions Source Reading Map](/fullstack/backend-metadata-to-frontend-table-actions-source-reading-map)** — trace the Student row-action chain in file order
+> 3. **[Backend Metadata to Frontend Table Actions Debug Checklist](/fullstack/backend-metadata-to-frontend-table-actions-debug-checklist)** — verify which layer is wrong when the visible action still fails
+>
+> **You are here:** step 3.
+> **Previous recommended pages:** [Backend Metadata to Frontend Table Actions](/fullstack/backend-metadata-to-frontend-table-actions) and [Backend Metadata to Frontend Table Actions Source Reading Map](/fullstack/backend-metadata-to-frontend-table-actions-source-reading-map).
+
+## Why this page exists
+
+The current docs already explain the mixed chain in two useful ways:
+
+- conceptually, through the mixed-chain explainer page
+- structurally, through the mixed-chain source-reading map
+
+What was still missing was one page that starts from symptoms.
+
+This page fills that gap.
+
+It is not another contract-loop overview and not another table-runtime deep dive. It is a practical checklist for debugging one Student row-action chain.
+
+## Fastest mental model for diagnosis
+
+A visible row action can fail at several different layers:
+
+1. backend row metadata may not point to the intended action resource
+2. custom backend action semantics may not have refreshed the generated frontend contract surface
+3. the frontend action resource may be missing or stale
+4. the page block/runtime handoff may not be feeding the right row schema into `ZTable`
+5. the table runtime may finally be filtering or resolving the action differently than expected
+
+The fastest debugging strategy is:
+
+> check the earliest possible source of truth first, and only descend into deeper runtime layers when the earlier layers already look correct.
+
+## Debugging checklist by layer
+
+### 1. Check the backend row metadata first
+
+Start here when:
+
+- the action is missing entirely
+- the wrong action appears in the operations column
+- the custom action is not present in the backend contract surface at all
+
+Primary source anchor:
+
+- `vona/src/suite/a-training/modules/training-student/src/dto/studentSelectResItem.tsx`
+
+What to confirm:
+
+- the row metadata still uses the intended `ZovaRender.cell(...)` identity
+- nested `ZovaRender.tableActionRow(...)` entries include the expected action names
+- custom actions such as `training-student:actionSummary` or `training-student:actionDeleteForce` are still present where expected
+
+If this layer is wrong, stop here and fix the metadata truth first.
+
+### 2. Check the forward-generated contract only when custom action semantics changed
+
+Only do this when the visible action depends on a changed backend endpoint such as:
+
+- `summary/:id`
+- `deleteForce/:id`
+
+Primary source anchors:
+
+- `vona/src/suite/a-training/modules/training-student/src/controller/student.ts`
+- `zova/src/suite/a-training/modules/training-student/cli/openapi.config.ts`
+- `zova/src/suite/a-training/modules/training-student/src/api/trainingStudent.ts`
+- `zova/src/suite/a-training/modules/training-student/src/model/student.ts`
+
+What to confirm:
+
+- the backend controller still exposes the intended custom endpoint
+- the frontend module OpenAPI config still owns the expected operation slice
+- the generated frontend API surface still contains the expected typed method
+- the thin model facade still delegates to the correct generated API path while keeping the existing resource-owner story intact
+
+If the endpoint changed but the generated contract did not refresh, the issue is not the visible action resource yet.
+It is a forward-chain regeneration problem.
+
+### 3. Check that the frontend action resource exists and matches the metadata identity
+
+Start here when:
+
+- backend metadata looks correct
+- generated contract also looks correct
+- but the visible action still does not render or behaves like the wrong action implementation
+
+Primary source anchors:
+
+- `zova/src/suite/a-training/modules/training-student/src/bean/tableCell.actionSummary.tsx`
+- `zova/src/suite/a-training/modules/training-student/src/bean/tableCell.actionDeleteForce.tsx`
+- `zova/src/suite/cabloy-basic/modules/basic-table/src/bean/tableCell.actionOperationsRow.tsx`
+
+What to confirm:
+
+- the expected custom or built-in action bean exists
+- the resource identity in backend metadata still matches the frontend bean identity
+- the custom action bean is still thin and delegates to the right model or command path
+- `actionOperationsRow` is still able to include and render the child action resources
+
+### 4. Check the page handoff into the list/table runtime
+
+Start here when:
+
+- backend metadata and action resources both look correct
+- but the list page still does not expose the action as expected
+
+Primary source anchors:
+
+- `zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockPage/controller.tsx`
+- `zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockTable/controller.tsx`
+
+What to confirm:
+
+- `schemaRow` is still exposed from the stable resource owner
+- `permissions` are still flowing through the shared page runtime
+- `blockTable` is still bridging the expected `schemaRow`, `data`, and `tableScope` into `ZTable`
+
+If this layer is wrong, the problem is in the page/runtime handoff, not in the action bean itself.
+
+### 5. Only then check final table/runtime resolution
+
+Go here last when:
+
+- metadata truth is correct
+- generated contract is correct
+- action resources exist
+- page block handoff also looks correct
+- but the action still renders incorrectly
+
+Primary final-runtime anchor:
+
+- `zova/src/suite-vendor/a-zova/modules/a-table/src/component/table/controller.tsx`
+
+At this point, switch from contract debugging into deeper table-runtime debugging.
+
+For the broader table runtime reading path, continue with [Zova Table Source Reading Map](/frontend/zova-table-source-reading-map).
+
+## How to classify the failure
+
+### Visible action missing entirely
+
+Most likely checks, in order:
+
+1. backend row metadata truth
+2. frontend action resource identity exists
+3. page block/schema handoff
+
+### Visible action exists but uses stale behavior
+
+Most likely checks, in order:
+
+1. if custom semantics changed, inspect the forward-generated contract path
+2. distinguish generated-output drift from local dependency drift
+3. then confirm the action bean still delegates to the expected model/API path
+
+### Visible action exists but wrong permissions or visibility
+
+This is often a narrower visibility problem rather than a full mixed-chain problem.
+
+When that is the real issue, continue with [Table Action Visibility and Permission Flow Guide](/frontend/table-action-visibility-permission-flow-guide).
+
+### Visible action exists but wrong runtime/render resolution
+
+Treat this as the deepest layer.
+
+Only go here after upstream contract, generation, action-resource, and page handoff checks already pass.
+
+## Generated-output drift vs local dependency drift
+
+A useful distinction is:
+
+### Generated-output drift
+
+This is the problem when:
+
+- the custom backend contract changed
+- but the generated frontend API/model surface was not refreshed correctly
+
+Typical response:
+
+1. confirm backend contract truth first
+2. refresh the generated frontend contract surface
+3. verify the generated output itself before debugging the visible action
+
+### Local dependency drift
+
+This is the problem when:
+
+- the generated output already contains the expected action contract or types
+- but local consumers still behave as if the old version is installed
+
+Typical response:
+
+1. stop editing source truth
+2. prove the generated handoff is already correct
+3. rerun the normal sync flow
+4. only then repair local install state if needed
+
+For the broader drift vocabulary, continue with [Contract Loop Playbook](/fullstack/contract-loop-playbook).
+
+## What this page does not re-explain
+
+This page deliberately does **not** re-teach:
+
+- generic contract-loop direction and drift theory -> see [Contract Loop Playbook](/fullstack/contract-loop-playbook)
+- the conceptual mixed-chain story -> see [Backend Metadata to Frontend Table Actions](/fullstack/backend-metadata-to-frontend-table-actions)
+- the file-order mixed-chain path -> see [Backend Metadata to Frontend Table Actions Source Reading Map](/fullstack/backend-metadata-to-frontend-table-actions-source-reading-map)
+- table-action permission semantics in depth -> see [Table Action Visibility and Permission Flow Guide](/frontend/table-action-visibility-permission-flow-guide)
+- deep table runtime internals -> see [Zova Table Source Reading Map](/frontend/zova-table-source-reading-map)
+
+Its job is only to tell you which layer to verify next when the visible Student row action still fails.
+
+## Where to read next
+
+- If you need the conceptual mixed-chain explanation first, return to [Backend Metadata to Frontend Table Actions](/fullstack/backend-metadata-to-frontend-table-actions).
+- If you need the file-order path first, continue with [Backend Metadata to Frontend Table Actions Source Reading Map](/fullstack/backend-metadata-to-frontend-table-actions-source-reading-map).
+- If you want a proof-oriented layer-by-layer validation workflow after making a change, continue with [Backend Metadata to Frontend Table Actions Verify Playbook](/fullstack/backend-metadata-to-frontend-table-actions-verify-playbook).
+- If the issue is really visibility/permission logic, continue with [Table Action Visibility and Permission Flow Guide](/frontend/table-action-visibility-permission-flow-guide).
+- If the mixed-chain layer itself now looks correct and you want the frontend consumer-side diagnosis family, continue with [Generated Contract Consumption Debug Checklist](/frontend/generated-contract-consumption-debug-checklist).
+- If the issue becomes deep table-runtime resolution, descend into [Zova Table Source Reading Map](/frontend/zova-table-source-reading-map).
+
+## Final takeaway
+
+The cleanest way to debug a visible Student row action is not to start from the deepest table runtime file.
+
+Start from backend row metadata truth, then only move into generated contract follow-up, action resource existence, page handoff, and final runtime resolution as needed.

package/cabloy-docs/fullstack/backend-metadata-to-frontend-table-actions-source-reading-map.md

@@ -0,0 +1,139 @@
+# Backend Metadata to Frontend Table Actions Source Reading Map
+
+This page is a practical source-reading companion for one narrow fullstack question:
+
+> if I need to trace one Student row-action chain across backend metadata, generated contract follow-up, and frontend action resources, which files should I open first, and in what order?
+
+Use this page together with:
+
+- [Backend Metadata to Frontend Table Actions](/fullstack/backend-metadata-to-frontend-table-actions)
+- [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
+- [Frontend Metadata Back to Backend](/fullstack/frontend-metadata-to-backend)
+- [TableCell Authoring Cookbook](/frontend/table-cell-cookbook)
+- [Table + Resource CRUD Cookbook](/frontend/table-resource-crud-cookbook)
+- [Table Action Visibility and Permission Flow Guide](/frontend/table-action-visibility-permission-flow-guide)
+
+> [!TIP]
+> **Mixed-chain reading path**
+>
+> 1. **[Backend Metadata to Frontend Table Actions](/fullstack/backend-metadata-to-frontend-table-actions)** — understand the mixed contract chain conceptually
+> 2. **[Backend Metadata to Frontend Table Actions Source Reading Map](/fullstack/backend-metadata-to-frontend-table-actions-source-reading-map)** — trace the same Student row-action chain in file order
+>
+> **You are here:** step 2.
+> **Previous recommended page:** [Backend Metadata to Frontend Table Actions](/fullstack/backend-metadata-to-frontend-table-actions).
+
+## Why this page exists
+
+The current mixed-chain explainer page already answers the conceptual question well:
+
+- backend metadata chooses frontend action resources
+- generated API/model follow-up can join that same thread when custom actions need backend endpoints
+- the visible row action is only the last step of the chain
+
+What it does not isolate directly is the shortest source-order path through one real Student row-action thread.
+
+This page fills that gap.
+
+It is a file-order map, not another runtime explainer.
+
+## How to use this page
+
+For the two paths below:
+
+1. start with the conceptual mixed-chain page first
+2. read the first source file to identify the current source of truth
+3. follow the handoff only until you can answer the question you actually have
+4. stop before you drift into deeper table/runtime internals unless they are really needed
+
+## 1. Built-in row-action chain
+
+Use this path when your question is about:
+
+- how one built-in row action becomes visible
+- how `actionOperationsRow` composes visible child actions
+- where backend metadata stops and frontend action resources start
+
+### Read the docs first
+
+- [Backend Metadata to Frontend Table Actions](/fullstack/backend-metadata-to-frontend-table-actions)
+- [Table Action Visibility and Permission Flow Guide](/frontend/table-action-visibility-permission-flow-guide)
+- [TableCell Authoring Cookbook](/frontend/table-cell-cookbook)
+
+### Then read source in this order
+
+1. `vona/src/suite/a-training/modules/training-student/src/dto/studentSelectResItem.tsx`
+2. `zova/src/suite/cabloy-basic/modules/basic-table/src/bean/tableCell.actionOperationsRow.tsx`
+3. `zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockPage/controller.tsx`
+4. `zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockTable/controller.tsx`
+
+### What each file clarifies
+
+- `studentSelectResItem.tsx` shows the backend-owned row DTO metadata that chooses `basic-table:actionOperationsRow` and the visible child actions inside it
+- `tableCell.actionOperationsRow.tsx` shows how the frontend runtime filters those child actions by permission and renders them through nested action resources
+- `blockPage/controller.tsx` shows how `schemaRow`, `permissions`, and list data are exposed from the stable resource owner into the page runtime
+- `blockTable/controller.tsx` shows the bridge from page runtime into `ZTable`
+
+## 2. Custom action chain with generated contract follow-up
+
+Use this path when your question is about:
+
+- how a custom row action such as `summary` or `deleteForce` joins the mixed chain
+- where the forward-generated API/model path enters
+- how the visible action stays thin while backend truth and resource ownership remain coherent
+
+### Read the docs first
+
+- [Backend Metadata to Frontend Table Actions](/fullstack/backend-metadata-to-frontend-table-actions)
+- [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
+- [Frontend Metadata Back to Backend](/fullstack/frontend-metadata-to-backend)
+
+### Then read source in this order
+
+1. `vona/src/suite/a-training/modules/training-student/src/controller/student.ts`
+2. `vona/src/suite/a-training/modules/training-student/src/dto/studentSelectResItem.tsx`
+3. `zova/src/suite/a-training/modules/training-student/cli/openapi.config.ts`
+4. `zova/src/suite/a-training/modules/training-student/src/api/trainingStudent.ts`
+5. `zova/src/suite/a-training/modules/training-student/src/model/student.ts`
+6. `zova/src/suite/a-training/modules/training-student/src/bean/tableCell.actionSummary.tsx`
+7. `zova/src/suite/a-training/modules/training-student/src/bean/tableCell.actionDeleteForce.tsx`
+8. optional downstream handoff:
+   - `zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockPage/controller.tsx`
+   - `zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockTable/controller.tsx`
+
+### What each file clarifies
+
+- `controller/student.ts` shows the backend source truth for custom endpoints such as `summary/:id` and `deleteForce/:id`
+- `studentSelectResItem.tsx` shows the backend row metadata that inserts the custom row actions into the operations column
+- `openapi.config.ts` shows the frontend module ownership rule for generated OpenAPI operations
+- `api/trainingStudent.ts` shows the generated typed API surface that the frontend can consume
+- `model/student.ts` shows the thin semantic facade over the stable resource owner
+- `tableCell.actionSummary.tsx` shows a visible action that stays thin and delegates summary behavior into the model/API path
+- `tableCell.actionDeleteForce.tsx` shows the same pattern for force-delete behavior
+- `blockPage` and `blockTable` are only needed when the question becomes “how does the list runtime carry that row schema into visible table output?”
+
+## What this page does not re-explain
+
+This page deliberately does **not** re-teach:
+
+- generic table runtime internals -> see [Zova Table Source Reading Map](/frontend/zova-table-source-reading-map)
+- CRUD list-page assembly -> see [Table + Resource CRUD Cookbook](/frontend/table-resource-crud-cookbook)
+- row/bulk permission filtering semantics -> see [Table Action Visibility and Permission Flow Guide](/frontend/table-action-visibility-permission-flow-guide)
+- the pure forward bridge -> see [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
+- the pure reverse bridge -> see [Frontend Metadata Back to Backend](/fullstack/frontend-metadata-to-backend)
+
+Its job is only to provide the shortest file-order path through one mixed Student row-action chain.
+
+## Where to read next
+
+- If you need the conceptual mixed-chain explanation first, return to [Backend Metadata to Frontend Table Actions](/fullstack/backend-metadata-to-frontend-table-actions).
+- If you now want to prove the Student row-action chain end-to-end after a change, continue with [Backend Metadata to Frontend Table Actions Verify Playbook](/fullstack/backend-metadata-to-frontend-table-actions-verify-playbook).
+- If the visible Student row action is still wrong after you understand the file-order path, continue with [Backend Metadata to Frontend Table Actions Debug Checklist](/fullstack/backend-metadata-to-frontend-table-actions-debug-checklist).
+- If your next question is purely forward-chain, continue with [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk).
+- If your next question is purely reverse-chain, continue with [Frontend Metadata Back to Backend](/fullstack/frontend-metadata-to-backend).
+- If your next question becomes table-runtime specific, continue with [Zova Table Source Reading Map](/frontend/zova-table-source-reading-map) and [Table Action Visibility and Permission Flow Guide](/frontend/table-action-visibility-permission-flow-guide).
+
+## Final takeaway
+
+The cleanest way to read a mixed Student row-action chain is not to jump directly into either the backend bridge docs or the deepest table runtime files.
+
+Start from the backend row metadata that chooses the visible action resources, then follow the custom forward-generated path only when the action semantics actually require new backend endpoints.

package/cabloy-docs/fullstack/backend-metadata-to-frontend-table-actions-verify-playbook.md

@@ -0,0 +1,248 @@
+# Backend Metadata to Frontend Table Actions Verify Playbook
+
+This page is a proof-oriented verification companion for one narrow fullstack question:
+
+> after I change a Student row-action chain, what do I need to verify layer by layer before I trust the result?
+
+Use this page together with:
+
+- [Backend Metadata to Frontend Table Actions](/fullstack/backend-metadata-to-frontend-table-actions)
+- [Backend Metadata to Frontend Table Actions Debug Checklist](/fullstack/backend-metadata-to-frontend-table-actions-debug-checklist)
+- [Backend Metadata to Frontend Table Actions Source Reading Map](/fullstack/backend-metadata-to-frontend-table-actions-source-reading-map)
+- [Contract Loop Playbook](/fullstack/contract-loop-playbook)
+- [Table Action Visibility and Permission Flow Guide](/frontend/table-action-visibility-permission-flow-guide)
+
+> [!TIP]
+> **Mixed-chain verification path**
+>
+> 1. **[Backend Metadata to Frontend Table Actions](/fullstack/backend-metadata-to-frontend-table-actions)** — understand the mixed chain conceptually
+> 2. **[Backend Metadata to Frontend Table Actions Source Reading Map](/fullstack/backend-metadata-to-frontend-table-actions-source-reading-map)** — trace the Student row-action chain in file order
+> 3. **[Backend Metadata to Frontend Table Actions Verify Playbook](/fullstack/backend-metadata-to-frontend-table-actions-verify-playbook)** — prove the chain is correct after your change
+> 4. **[Backend Metadata to Frontend Table Actions Debug Checklist](/fullstack/backend-metadata-to-frontend-table-actions-debug-checklist)** — use only when the visible result is still wrong
+>
+> **You are here:** step 3.
+> **Previous recommended pages:** [Backend Metadata to Frontend Table Actions](/fullstack/backend-metadata-to-frontend-table-actions) and [Backend Metadata to Frontend Table Actions Source Reading Map](/fullstack/backend-metadata-to-frontend-table-actions-source-reading-map).
+
+## Why this page exists
+
+The current mixed-chain family already gives you three useful views:
+
+- the conceptual chain
+- the file-order source-reading path
+- the symptom-first debug checklist
+
+What it did not yet isolate directly was a **proof-oriented verification workflow**.
+
+This page fills that gap.
+
+It is not another diagnosis page. It is a playbook for proving one Student row-action chain is correct after a change.
+
+## Fastest mental model for verification
+
+A mixed Student row-action change is usually correct only when all of these are true:
+
+1. backend metadata truth still points to the intended action resources
+2. if custom semantics changed, the generated frontend contract surface is refreshed correctly
+3. the frontend action resources still align with the intended identities and behavior
+4. the page/runtime handoff still carries the expected row schema and permissions into `ZTable`
+5. the visible Admin behavior matches the intended contract
+
+The fastest verification strategy is:
+
+> prove each layer in order, and only classify drift or runtime issues after those proofs already pass.
+
+## Phase 1: Scope the branch first
+
+Before checking files, decide what kind of change you actually made.
+
+### Mostly reverse-chain
+
+Use this path when:
+
+- you changed only which frontend action resource a row or field metadata points to
+- no new backend endpoint or response contract is needed
+- the visible change is mostly metadata-driven
+
+Typical examples:
+
+- switching a field to `basic-table:actionView`
+- adding or reordering actions under `actionOperationsRow`
+- changing a custom frontend action resource that backend metadata references
+
+### Mostly forward-chain
+
+Use this path when:
+
+- the action semantics changed because backend endpoint truth changed
+- frontend generated API consumers must regenerate
+- the visible row action is only the last step of a backend-contract change
+
+Typical examples:
+
+- adding or changing `summary`
+- adding or changing `deleteForce`
+
+### True mixed custom-action case
+
+Use this path when both are true:
+
+- backend endpoint truth changed
+- backend row metadata also points to custom frontend action resources that expose the result visibly
+
+That is the full mixed-chain case this playbook is built for.
+
+## Phase 2: Prove backend source truth
+
+Start with the earliest source of truth that should already be correct.
+
+Primary anchors:
+
+- `vona/src/suite/a-training/modules/training-student/src/dto/studentSelectResItem.tsx`
+- `vona/src/suite/a-training/modules/training-student/src/controller/student.ts`
+- `vona/src/suite/a-training/modules/training-student/src/dto/studentSummary.tsx`
+
+What to prove:
+
+- row metadata still points to the intended action resources
+- the controller still exposes the intended custom endpoint when one exists
+- the response/request DTO truth still matches the intended action semantics
+
+If this phase fails, stop here.
+Do not debug frontend runtime yet.
+
+## Phase 3: Prove the emitted/generated handoff
+
+Only do this when the change touches custom action semantics or any backend-owned contract shape.
+
+Primary anchors:
+
+- `zova/src/suite/a-training/modules/training-student/cli/openapi.config.ts`
+- `zova/src/suite/a-training/modules/training-student/src/api/trainingStudent.ts`
+- any reverse-shared generated output already relevant to the Student row-action path
+
+What to prove:
+
+- the frontend module still owns the expected generated OpenAPI slice
+- the generated frontend API surface contains the expected custom method or changed contract
+- if the change is reverse-sharing oriented, the refreshed metadata/build handoff is already correct before debugging downstream consumers
+
+If this phase fails, the problem is still in the handoff/generation layer, not in the visible action resource.
+
+## Phase 4: Prove frontend resource alignment
+
+Once contract handoff looks correct, prove that the frontend action/resource layer still aligns with it.
+
+Primary anchors:
+
+- `zova/src/suite/a-training/modules/training-student/src/model/student.ts`
+- `zova/src/suite/a-training/modules/training-student/src/bean/tableCell.actionSummary.tsx`
+- `zova/src/suite/a-training/modules/training-student/src/bean/tableCell.actionDeleteForce.tsx`
+- `zova/src/suite/cabloy-basic/modules/basic-table/src/bean/tableCell.actionOperationsRow.tsx`
+
+What to prove:
+
+- the custom or built-in action bean identity still matches the backend metadata identity
+- thin model facades still delegate to the intended generated API/model path
+- the action bean is still thin and semantic rather than acting like a second competing resource owner
+- `actionOperationsRow` can still include and render the intended child actions
+
+## Phase 5: Prove page/runtime handoff
+
+Only now move into the page runtime handoff.
+
+Primary anchors:
+
+- `zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockPage/controller.tsx`
+- `zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockTable/controller.tsx`
+
+What to prove:
+
+- `schemaRow` still contains the intended row-action metadata
+- `permissions` still flow into the page runtime as expected
+- `blockTable` still bridges the expected `schemaRow`, `data`, and `tableScope` into `ZTable`
+
+If this phase fails, the issue is no longer contract definition or action resource alignment. It is the list/runtime handoff.
+
+## Phase 6: Prove visible Admin behavior
+
+Only after the earlier phases pass should you treat the page as ready for visible behavior checks.
+
+What to prove in Admin:
+
+- the expected row action is visible where it should be
+- built-in or custom action ordering still matches the metadata truth
+- custom action execution still uses the intended behavior
+- after execution, the list/runtime state still matches the expected refresh/invalidation result
+
+This is the point where the row-action chain becomes user-visible rather than just structurally correct.
+
+## Phase 7: Classify drift only after proof steps
+
+If the result is still wrong after the earlier phases, then classify the problem.
+
+### Generated-output drift
+
+This is the problem when:
+
+- backend or reverse-shared source truth changed
+- but the generated/shared handoff is still stale or incomplete
+
+### Local dependency drift
+
+This is the problem when:
+
+- the generated/shared output already looks correct
+- but local consumers still behave as if the old version is installed
+
+### Visibility-only issue
+
+This is the problem when:
+
+- the action exists and the contract chain is correct
+- but the action is hidden only by permissions or visibility logic
+
+When that is the true problem, continue with [Table Action Visibility and Permission Flow Guide](/frontend/table-action-visibility-permission-flow-guide).
+
+### Deeper table-runtime resolution issue
+
+This is the problem when:
+
+- metadata truth, generated handoff, frontend action alignment, and page handoff all already look correct
+- but the final visible action still resolves incorrectly
+
+Only then descend into the deeper table runtime docs.
+
+## What this page does not re-explain
+
+This page deliberately does **not** re-teach:
+
+- generic contract-loop direction and drift theory -> see [Contract Loop Playbook](/fullstack/contract-loop-playbook)
+- the conceptual mixed-chain story -> see [Backend Metadata to Frontend Table Actions](/fullstack/backend-metadata-to-frontend-table-actions)
+- the file-order mixed-chain path -> see [Backend Metadata to Frontend Table Actions Source Reading Map](/fullstack/backend-metadata-to-frontend-table-actions-source-reading-map)
+- the symptom-first diagnosis path -> see [Backend Metadata to Frontend Table Actions Debug Checklist](/fullstack/backend-metadata-to-frontend-table-actions-debug-checklist)
+- deep visibility/permission semantics -> see [Table Action Visibility and Permission Flow Guide](/frontend/table-action-visibility-permission-flow-guide)
+- deep table-runtime internals -> see [Zova Table Source Reading Map](/frontend/zova-table-source-reading-map)
+
+Its job is only to tell you what must be true at each layer before you trust the changed Student row-action chain.
+
+## Where to read next
+
+- If you need the conceptual mixed-chain page, return to [Backend Metadata to Frontend Table Actions](/fullstack/backend-metadata-to-frontend-table-actions).
+- If you need the file-order path, continue with [Backend Metadata to Frontend Table Actions Source Reading Map](/fullstack/backend-metadata-to-frontend-table-actions-source-reading-map).
+- If the visible result is still wrong and you want symptom-first diagnosis, continue with [Backend Metadata to Frontend Table Actions Debug Checklist](/fullstack/backend-metadata-to-frontend-table-actions-debug-checklist).
+- If the issue is really about direction/drift theory, return to [Contract Loop Playbook](/fullstack/contract-loop-playbook).
+- If the bridge and mixed-chain proof already look correct and you now want the consumer-side verification family, continue with [Generated Contract Consumption Verify Playbook](/frontend/generated-contract-consumption-verify-playbook) and [Generated Contract Consumption Debug Checklist](/frontend/generated-contract-consumption-debug-checklist).
+
+## Final takeaway
+
+The cleanest way to verify a changed Student row-action chain is not to jump straight into deep runtime debugging.
+
+First prove:
+
+- backend source truth
+- generated/shared handoff
+- frontend action/resource alignment
+- page/runtime handoff
+- visible Admin behavior
+
+Only then classify drift or descend into deeper runtime issues.