Cabloy Resource Field Update

Cabloy Resource Field Update

Use this skill when the user wants to change a field on an existing Vona backend resource.

Important recovery note for stale generated consumers

When the generated .zova-rest artifacts already contain the expected new keys or types but Vona still sees stale consumer types, treat that first as a local dependency drift problem rather than a source-editing problem.

In that situation:

1. run the normal sync flow, including the relevant Zova build first and then npm run deps:vona
2. if the generated .zova-rest artifacts already contain the expected changes but the stale behavior remains, rebuild vona/node_modules and reinstall dependencies

Keep this recovery rule visible during renderer-aware or contract-loop follow-up work. Do not keep debugging source-level renderer registrations until the local file-package installation state is known to be healthy.

Goals

1. detect whether the active repository is Cabloy Basic or Cabloy Start
2. classify the task as a new persisted field or a metadata-only field refinement
3. force the correct fileVersion decision before persistence edits
4. keep the workflow entity-first and inferred-DTO-first
5. prefer shared renderer reuse unless the task explicitly asks for a custom renderer demo
6. finish with verification guidance that matches backend and renderer follow-up scope

Step 1: Detect repo and confirm existing-resource scope

Check the repository root for these marker files:

• __CABLOY_BASIC__
• __CABLOY_START__

Interpretation:

• only __CABLOY_BASIC__ present → this is Cabloy Basic
• only __CABLOY_START__ present → this is Cabloy Start
• both markers present → treat the repository as ambiguous or invalid and stop before making edition-specific assumptions
• neither marker present → inspect the owning package scripts and nearby repository structure, then ask before making an edition-specific assumption

Then confirm the request is about an existing resource field.

Use this skill for requests such as:

• add a field to an existing resource
• tighten validation for an existing field
• add enum-like constraints to an existing field
• add or change ZovaRender.field(...) / ZovaRender.cell(...)
• decide whether a persisted field change needs a new fileVersion
• demonstrate a custom renderer workflow for a backend field

Do not use this skill when the user is really asking to create a new module, bean, CRUD thread, page thread, or stale consumer diagnosis flow.

If the request is really about initial backend thread creation, prefer cabloy-backend-scaffold. If the request is really about stale generated frontend/backend consumers, prefer cabloy-contract-loop. If the request is mainly about choosing a workflow, prefer cabloy-workflow.

Step 2: Classify the field change before editing

Branch the request into one of two cases.

Case A: new persisted field

Examples:

• add level: number
• add status: string
• add a new stored relation key

This case affects persistence and versioning.

Case B: metadata-only or validation/render-only refinement

Examples:

• add enum validation to an existing field
• add or change ZovaRender.field(...)
• add or change ZovaRender.cell(...)
• refine locale labels
• tighten validation without changing storage shape

This case usually does not require a fileVersion bump, because the persisted field already exists.

Step 3: Force the fileVersion decision for new persisted fields

If the task is a new persisted field on an existing resource, ask whether vonaModule.fileVersion should be incremented before changing:

• meta.version.ts
• the module schema version path
• the module package.json fileVersion

If the user says yes

Then:

1. bump vonaModule.fileVersion
2. add a new migration branch in meta.version.ts
3. preserve older version branches as historical snapshots
4. introduce the new persisted field in the new version branch

Important warning:

• do not add the same new column to an older create path and again to a new migration branch
• fresh install may run version branches sequentially
• that pattern can produce duplicate-column failures

If the user says no

Then:

1. keep the current fileVersion
2. fold the schema change into the current version path
3. do not create a new migration branch

Step 4: Inspect the current backend thread first

Before proposing or making edits, inspect the existing thread:

• entity
• model
• DTOs
• controller
• service
• meta.version.ts
• module package.json
• locale files
• tests

Also inspect the shared entrypoints first:

• root package.json
• npm run vona
• npm run zova

Use these references for compact support material:

• references/field-update-decision-tree.md
• references/follow-up-checklist.md
• references/verification-checklist.md

Step 5: Update the entity first and reuse inferred DTO flow

Treat the entity as the primary field-definition surface.

Typical field-update changes belong here first:

• @Api.field(...)
• v.required() / v.optional()
• v.title($locale(...))
• ZovaRender.order(...)
• explicit zod schema for constrained values

For enum-like numeric or string values, prefer an explicit constrained schema such as:

• z.union([z.literal(1), z.literal(2), z.literal(3)])

Ordering rule:

• framework-level guarding now preserves previously attached OpenAPI metadata across schema rebuilds, so metadata-only helpers are less order-sensitive than before
• this only removes metadata-loss order pitfalls; it does not make all schemaLike arguments fully order-independent
• when an explicit zod/custom schema or other structure-shaping schemaLike is passed into @Api.field(...), keep that structure-defining schemaLike as the last argument unless a local pattern clearly requires otherwise
• treat helpers such as v.object(...), v.array(...), v.optional(), v.nullable(), v.default(...), and preprocess/transform wrappers as structure-shaping, not metadata-only
• keep helper metadata such as v.xxx(...) and ZovaRender.xxx(...) before the final structure-defining schemaLike
• after edits involving structure-shaping schemaLike, verify the emitted schema/OpenAPI result instead of assuming reorder is safe

Then check whether DTOs are already inferred through patterns such as:

• $Dto.create(...)
• $Dto.update(...)
• $Dto.get(...)

If the DTOs are inferred from the entity/model chain, let the entity change propagate. Do not hand-edit DTO field lists unless the source clearly requires it.

Important serialization reminder:

• if the returned field behavior depends on v.serializerTransform(...), v.serializerExclude(), v.serializerReplace(...), v.serializerGetter(...), or v.serializerCustom(...), do not assume those transforms run by default
• for performance reasons, Vona response serialization is opt-in per API action
• verify that the target controller action explicitly uses @Core.serializer() before concluding that serializer metadata is broken