Ergon Archon Write API Migration
Use this skill only after screen discovery, read API migration, and required table-rule audits are closed or explicitly deferred. In the current orchestration taxonomy, use ergon-migration-orchestration first to confirm the relevant Phase 4/5/6 gate.
This skill does not rediscover the screen from scratch. It starts from discovery, read API, and table-rule audit artifacts and decides whether write can be implemented safely, preferably by calling existing legacy routines or preserving generated trigger/package behavior instead of reimplementing all business rules in Java.
This skill must also classify whether a write operation is safe for direct table/platform persistence. Direct Praxis resource persistence is allowed only when the operation reaches WRITE_TABLE_DIRECT_SAFE; otherwise use WRITE_DB_BACKED_REQUIRED, WRITE_BLOCKED, or WRITE_DEFERRED.
When this skill designs or changes command DTOs, request/response DTOs, @Schema, @UISchema, @Filterable, x-ui, OpenAPI schemas, /schemas/filtered, HATEOAS/action metadata, or capabilities, also use praxis-dto-annotations and ergon-fieldspec-ui-contract. Use praxis-java-host-project when creating or changing a Java/Spring resource. Use praxis-resource-entity-lookup-backend when write payloads, actions, or related flows consume RESOURCE_ENTITY, OptionSourceRegistry, OptionSourceDescriptor, or /option-sources/{sourceKey}.
Platform Governance
Before designing, exposing, or implementing write metadata, apply the root
migration AGENTS.md. Classify the change as docs-apenas, local-pequena,
transversal, contrato-publico, or arquitetural, and record the canonical
owner in the phase plan/gate.
Before editing Java, docs, tests, DTOs, resources, or build files, run the
duplicate-module-root guard from ergon-migration-orchestration for the target
module/artifactId. A passing unit or parity test in a temporary
migracao-package clone is not implementation evidence for the versioned
canonical migration module.
Do not patch Praxis platform limitations inside the Ergon write endpoint or UI
contract. Before introducing @WorkflowAction, @UiSurface, capabilities,
availability rules, custom action models, or Angular workarounds, inventory the
native Praxis support and classify the need as ja-suportado-so-ux,
ja-suportado-mal-nomeado-ou-mal-materializado,
suportado-parcialmente, or lacuna-real-de-contrato.
HADES-backed permission and state decisions must remain server-side through
the approved Ergon bridge/starter and canonical Praxis availability extension
points. Public write metadata may expose only availability and public payload,
never HADES, SQL, ROWID, empresa, usuario, perfil, package flags, or session
context. Real Praxis gaps must be recorded as Praxis Platform Follow-up.
Phase Boundary
Use this as the write API migration skill for the current Phase 4/5/6 sequence: Phase 4 audits write behavior, Phase 5 closes the write contract, and Phase 6 implements approved operations. Older references may call this "Phase 3 - Write API Design"; map that wording to the current taxonomy before deciding gates.
ergon-archon-screen-discovery anchors the user workflow, XML/runtime SQL, read candidates, and write risk/handoff. It identifies candidate write actions and target routines/tables, but should not guess write parity from names alone.
ergon-archon-read-api-migration closes or implements read/query APIs before write API design. For read-first resources, require backend implementation evidence before write: service/controller tests for the read boundary, explicit blocked-write behavior for inherited generic CRUD, and at least one recorded smoke/parity result or a documented fixture blocker.
ergon-archon-write-api-migration consumes discovery, read API, and table-rule artifacts and closes one write operation at a time. It may implement Java only after target tables, routines, session context, permissions, rules, side effects, and parity cases are closed.
ergon-table-rule-audit is a required Phase 4 input for operations that can write data. Run it after write target tables are known from XML/runtime/handoff evidence and before this skill designs a write contract. Do not use it to replace screen discovery.
If the handoff does not identify write actions, target tables/routines, public key strategy, payload evidence, session context, operation status, or write blockers, stop and return to ergon-archon-screen-discovery. If table-rule audit summaries are missing for any target or side-effect table, return to ergon-table-rule-audit unless the operation is explicitly Blocked, Deferred, or Not API.
Phase Entry Gate
Before changing Java, command DTOs, public metadata, or API behavior, create or update the write package with an explicit entry-gate decision:
- Phase 1/2 discovery artifacts are closed for the operation, including component lineage, operation inventory, API contract, public key strategy, and read/write handoff.
- Phase 3 read API is implemented or explicitly not required for this operation; read-first resources have backend tests, blocked write behavior for unsupported operations, and read smoke/parity evidence.
- Phase 4 table-rule audit is complete for every target and known side-effect table, including HADES
HAD_CAD_SPROC, HAD_CAD_MULT_EPS, PACK_EXEC_SPROC, C_ERGON routines, generated trigger/package phases, nested dependencies, session context, and cleanup risks.
- The latest
ergon-table-rule-audit handoff decision is recorded as Write API safe to design, DB-backed write path required, Blocked, or Deferred. Only the first two may enter Phase 5 design.
praxis-dto-annotations, ergon-fieldspec-ui-contract, and praxis-java-host-project reviews are recorded before declaring Ready for implementation; praxis-resource-entity-lookup-backend is recorded when option sources participate in payloads, duplicate drafts, related resources, or action metadata.
- The operation has a named state:
Required Now, Ready for design, Ready for implementation, Implemented, Blocked, Deferred, Not API, or Not present.
If any required evidence is missing, do not design a compensating shortcut. Route the work back to the owning phase and record the exact blocker in write-api-handoff.md or write-contract.md.
Payload closure is a hard Phase 4/5 input. For standard Cronos
recordPanelEdit + dataTable, accept parser-valid XML plus local Cronos
framework source as payload evidence when it proves the route, _op, _p_,
_o_, _q_p_, editable fields, table metadata SQL generation, and
same-connection Oracle execution. When
tools/migration-factory/new-cronos-recordpanel-write-payload.ps1 exists,
require a passing -Strict run and generated Markdown/JSON under
docs/migracao/<SCREEN>/factory/.
For rotina/object-method/custom actions, or when XML/source does not prove the
route, the handoff must include browser/debug evidence for the actual payload
produced by the legacy UI, including operation selector, hidden locators,
business fields, publication fields, P_MENS, pending/legal/flex fields,
visible confirmation/validation messages, and cancel/no-op behavior. Do not
design command DTOs by copying all PL/SQL arguments when the screen only sends
or derives a subset.
Standard Write Operation Set
For Ergon framework screens, design writes by operation, not by generic CRUD alone. Start with this set and mark each operation as Implemented, Ready, Blocked, Deferred, or Not present:
Novo/Salvar: create command, defaults, required fields, legacy route, validation and cleanup.
Editar/Salvar: update command, immutable keys, changed fields, validation and side effects.
Apagar: delete/anulation command, confirmation, permission/dependency blockers, row preservation proof.
Duplicar: copied/defaulted fields, generated key strategy, usually create-route parity but not assumed.
Cancelar: no-mutation proof for create/edit/duplicate modes.
Documentos legais: legal-document read/write route, link key such as PONTLEI, component ownership, and whether it is a separate resource.
Publicacoes/atos and Pendencias: include when visible or reached by triggers/packages.
Do not declare a screen's backend "complete" while any visible operation from this set is merely absent from the contract. Either implement it, block it deliberately in the API/UI contract, or defer it with the exact missing evidence and risk.
Praxis Write Mapping
Use the standard Praxis metadata/API resource surface as the API contract, but choose the implementation route by legacy evidence:
Novo/Salvar: expose POST /<resource> and implement through BaseResourceCommandService.create only when direct platform persistence is safe. For legacy-generated DML, keep the endpoint but delegate to a screen-specific legacy write service using ErgonLegacyExecutor.
Editar/Salvar: expose PUT /<resource>/{id} and implement through BaseResourceCommandService.update; prefer a command DTO when the read DTO contains derived, hidden, or view-only fields.
Apagar: expose DELETE /<resource>/{id} and implement through BaseResourceCommandService.deleteById; enable DELETE /batch only after separate parity closure.
Duplicar: expose POST /<resource>/{id}/duplicate-draft only when the service implements DuplicateDraftResourceService.duplicateDraft; use DuplicateDraftUtils and @UISchema(copyOnDuplicate) for draft behavior, then persist with POST. Do not classify duplicate as @WorkflowAction merely because the legacy UI has a duplicate button.
Cancelar: do not create a backend mutation; prove no database change from create/edit/duplicate cancellation.
Documentos legais, Publicacoes/atos, and Pendencias: model as separate related resources/workflows unless the legacy XML/runtime route proves they are part of the main command.
When writes must preserve Ergon behavior, the Praxis resource method is only the HTTP/resource contract. The implementation must run same-connection FLAG_PACK setup/cleanup, call the chosen route (ERG_DML_*, screen procedure, direct table with triggers, or writable view), translate Oracle/Ergon errors, reload read DTOs through the public key, and record parity evidence.
Never create a parallel write contract because the canonical Praxis action/capability model or Ergon legacy bridge is inconvenient. If Praxis lacks an action, availability, schema, option-source, or error-envelope capability needed for a safe Ergon write, classify the platform gap and keep the operation blocked or deferred until the canonical contract is extended.
Classify every write-like operation against the Praxis semantic contract before exposing metadata:
- Simple create, update, and delete remain resource operations when Phase 4/5 proves the route is safe.
- Partial same-resource maintenance may use
@ResourceIntent when it needs a named intent but still belongs to the resource contract.
- Related tabs, read projections, embedded maintenance, legal documents, publications, and pending work are
@UiSurface or separate related resources unless runtime evidence proves they are part of the same command.
- Business commands such as approve, cancel business state, reopen, publish, generate pending work, or other non-CRUD side-effect operations are
@WorkflowAction. Duplicate is @WorkflowAction only when runtime evidence proves a business command with its own immediate effect, dedicated routine, pending/publication side effect, or semantics beyond preparing an editable create draft; otherwise use duplicate-draft + POST.
- Availability should use canonical Praxis capabilities/actions/surfaces. For HADES-backed permission or state decisions, use the existing HADES starter/
HadesLegacyAccessGuard/legacy bridge plus optional Praxis rules such as ActionAvailabilityRule, SurfaceAvailabilityRule, and ResourceStateSnapshotProvider; do not expose HADES, SQL, ROWID, empresa, usuario, or raw session context in public metadata.
Route safety states:
WRITE_TABLE_DIRECT_CANDIDATE: direct table/platform persistence may be viable, but evidence is not closed.
WRITE_TABLE_DIRECT_SAFE: direct table/platform persistence is approved for the exact operation. This requires proof that it covers or safely excludes active product/client rules, HADES/EP behavior, package-only logic, side effects, session context, error mapping, transaction behavior, cleanup, and parity.
WRITE_DB_BACKED_REQUIRED: use the validated DB-backed route because direct table persistence would skip or might skip required behavior.
WRITE_BLOCKED: missing or contradictory evidence prevents implementation.
WRITE_DEFERRED: explicitly out of scope.
Unknown means not safe. If any route coverage, side effect, HADES/client behavior, session context, error precedence, or cleanup path is unknown, do not mark WRITE_TABLE_DIRECT_SAFE.
Supporting Skills
Use ergon-table-rule-audit before this skill after the write target tables are known. This skill may request additional table audits when operation design reveals side-effect tables not covered in Phase 4.
Use praxis-dto-annotations during Phase 5 contract work before marking command DTOs, request/response DTOs, @Schema, @UISchema, @Filterable, x-ui, or /schemas/filtered as closed. Use ergon-fieldspec-ui-contract to validate schema/action/capability metadata consumed by FieldSpec/Angular. Use praxis-java-host-project during Phase 6 implementation before changing resources/controllers/services. Use praxis-resource-entity-lookup-backend when governed option sources participate in write payloads, duplicate drafts, related resources, or action metadata.
It is not a replacement for screen discovery or XML analysis. It is the table-level rule audit used before choosing a write path. Run it for every base table that can be changed by the operation, including association/publication tables reached by triggers or packages.
Typical examples:
TIPO_FREQ_ and TIPO_FREQ_EMPRESA for ERGadm00033 type writes;
FREQUENCIAS and related publication/pending tables for ERGadm00189 frequency writes;
- any table named by
recordPanelEdit dataTable, generated DML procedure arguments, INSTEAD OF view triggers, or package side effects.
The audit must feed write-contract.md, plsql-error-map.md, and write-parity-matrix.md with:
- product rules from generated triggers,
PCK_<TABLE>, PCK_<TABLE>_PND, constraints, defaults, and generated DML procedures;
- client rules from
PCK_EXEC_EP_CERG, HADES HAD_CAD_SPROC / HAD_CAD_MULT_EPS, and C_ERGON routines;
- active/inactive status and execution order;
- the product/client execution matrix for package and trigger phases:
MAIN_PRE, trigger before, DML/AUX/audit, MAIN_POS, and trigger after;
- package EP semantics:
EPB__<TABLE> and EPA__<TABLE> can return v_ep plus P_MENS; v_ep = FALSE can skip only product code inside the relevant IF v_ep THEN block;
- trigger EP semantics:
EP_TRG_B_<TABLE> and EP_TRG_A_<TABLE> can block through P_MENS but do not return v_ep to skip MAIN_PRE or MAIN_POS;
- product rules explicitly classified as inside or outside the
IF v_ep THEN gate;
- nested dependency graph when Java may re-orchestrate or reimplement a rule;
- the migration decision for each rule:
Reimplement in Java, Keep DB-backed, Preserve extension hook, Audit/publication only, or Out of scope.
Save table-rule audit SQL and output under the screen package, preferably:
docs/migracao/<SCREEN>/oracle-results/table-rule-audit/
<TABLE>.sql
<TABLE>.out.txt
<TABLE>.summary.md
<TABLE>.nested-dependencies.sql
<TABLE>.nested-dependencies.out.txt
<TABLE>.dependency-graph.md
The canonical summary path is docs/migracao/<SCREEN>/oracle-results/table-rule-audit/<TABLE>.summary.md. The summary should be short and should contain only findings needed by the write decision, not full trigger/package source dumps. If a root-level table-rule-audit-<table>.md exists from exploratory work, link or migrate it into the canonical folder before closing the gate.
Required Inputs
Before using this skill, verify the screen package has:
closure-checklist.md with screen discovery closed for the intended slice;
component-lineage-matrix.md;
api-contract.md;
read-parity-matrix.md and read implementation/test evidence when reads were implemented;
read-parity-results.md when a read endpoint already exists, including commands/results, smoke fixture, remaining backend parity gaps, and any reason OpenAPI/x-ui checks are still planned;
write-risk.md;
write-risk-detail.sql and Oracle output when database access is available;
write-api-handoff.md;
operation-inventory.md or equivalent operation table listing list/detail/create/update/delete/duplicate/cancel/legal/publication/pending states;
platform-reuse-inventory.md or an equivalent explicit decision showing whether each write/related resource will reuse, extend, create, block, defer, or stay out of the API;
- runtime or source-derived write payload evidence for every operation being designed: for standard Cronos
recordPanelEdit + dataTable, a passing source-derived payload artifact is acceptable; for other actions use browser/debug payload evidence for Novo, Editar, Apagar, Duplicar, Salvar, Cancelar, or an explicit Not present / Blocked row;
- for
Duplicar, a decision proving whether the flow is duplicate-draft + POST, a dedicated legacy route, a real @WorkflowAction, Blocked, or Not present; duplicateEnabled=true alone is not enough;
- table-rule audit summaries for each target and known side-effect table, unless the operation is not proceeding beyond
Blocked/Deferred;
- implemented read API files when the current state is
Read API implemented.
If these are missing, return to the owning earlier phase instead of guessing write behavior: use ergon-archon-screen-discovery for missing lineage/handoff, ergon-archon-read-api-migration for missing read implementation or read parity evidence, and ergon-table-rule-audit for missing table-rule evidence.
Core Strategy
Prefer Legacy-backed Write API when possible:
- Java owns REST contract, authentication, authorization checks, payload validation, session context setup, transaction boundary, and error mapping.
- Oracle legacy routines, generated DML, triggers, and packages preserve business behavior.
- Java reimplementation is allowed only when the legacy routine is unsuitable and all validations, side effects, and parity cases are fully understood.
Do not expose generic CRUD merely because AbstractResourceController has create/update/delete hooks.
Do expose direct platform/table CRUD when, and only when, write-route-decision.md marks the operation WRITE_TABLE_DIRECT_SAFE and parity evidence supports it. This is a speed path, not a shortcut around rule audit.
Legacy Bridge Pattern
When a migrated service must talk to legacy write behavior for years while the full flow remains split between Java and Oracle, prefer a small shared bridge over ad hoc database calls in each resource.
The bridge should centralize:
- same-connection legacy context setup such as
HADES.FLAG_PACK.SET_USUARIO, SET_TRANSACAO, SET_EMPRESA, and optional SET_SIS/SET_ROLE;
- legacy user and company mapping through shared application hooks, such as
ErgonLegacyContextProvider, ErgonLegacyUserMapper, and ErgonLegacyCompanyResolver in ms-administracao-pessoal, so production IdP/company-session differences are not reimplemented per write service;
- transaction participation and cleanup/reset for pooled connections;
- invocation of the chosen route: generated
ERG_DML_*, direct table DML with generated triggers, writable view, or specific PL/SQL package;
- translation of
ORA-20xxx, HADES/Ergon validation messages, unique violations, dependency violations, and setup failures into stable API errors;
- operation metadata: screen/transaction, company, user, route name, and evidence links.
If no existing Praxis host/shared module already provides this capability, create or extend a runtime-neutral legacy bridge only when it stays independent of UI/editor code and does not import a business module. Keep screen-specific DML, SQL text, DTO mapping, and policy decisions in the application module.
Do not make JdbcTemplate the declared project standard just because the bridge uses JDBC internally. First inspect the target module and starter conventions. If the module uses Spring Data/JPA plus a starter, keep resource/service/repository code aligned with that convention and confine low-level JDBC to a shared executor only when same-connection package state or callable PL/SQL requires it. Document the deviation in write-route-decision.md.
Workflow
- Read
write-api-handoff.md, write-risk.md, api-contract.md, platform-reuse-inventory.md, and the read implementation files.
- Identify the write resource, operations, public key strategy, current read DTO, and UI write buttons using the Standard Write Operation Set.
- Inspect the Java project convention before selecting a persistence mechanism: existing write resources, starter-provided services/repositories, Spring Data/JPA repositories,
EntityManager, transaction/session helpers, and any project abstraction for calling PL/SQL or generated DML. If Phase 1.5 found an existing resource, prefer reusing/extending it over creating a parallel endpoint. Do not assume JdbcTemplate is the default merely because direct Oracle calls are needed. If no shared helper exists and same-connection package state is required, propose or implement a legacy bridge abstraction instead of scattering low-level JDBC.
- Inspect the Archon XML write component:
recordPanelEdit, dataTable, db:* routine, duplicate behavior, delete/anulacao behavior, linked publication/legal blocks, and hidden row keys.
- Inspect Oracle metadata for target tables, generated DML routines, triggers, grants, constraints, defaults, packages, package arguments, and source references.
- Run
ergon-table-rule-audit for each write target base table and each side-effect table that can be reached by triggers/packages.
- Convert table-rule audit findings into an operation-level product/client decision matrix. For each phase (
MAIN_PRE, trigger before, DML/AUX/audit, MAIN_POS, trigger after), classify the result as product only, client + product, client replaces gated product block, client blocks by P_MENS, inactive, or unknown/blocked. Identify product rules inside and outside IF v_ep THEN.
- Convert the matrix into operation-level decisions: which rules are covered by the chosen legacy write path, which require Java behavior, which are audit/publication only, which preserve a customer extension hook, and which are out of scope for this operation.
- If more than one persistence route exists, produce
write-route-decision.md from write-route-decision-template.md. Do not ask the developer to choose manually. Compare generated ERG_DML_*, direct base-table DML, writable view triggers, and screen-specific PL/SQL packages against the same fixture whenever possible.
- Decide the write strategy for each operation:
legacy-routine, direct-table-with-triggers, writable-view, java-reimplementation, blocked, or not-api.
Also record route safety state: WRITE_TABLE_DIRECT_SAFE, WRITE_DB_BACKED_REQUIRED, WRITE_BLOCKED, or WRITE_DEFERRED.
- Produce
write-contract.md from write-contract-template.md. Include the product/client decision matrix in the contract or link to the canonical table-rule audit summary that contains it. Record the applied praxis-dto-annotations and ergon-fieldspec-ui-contract review before marking Phase 5 ready.
- Produce
plsql-error-map.md from plsql-error-map-template.md.
- Produce
write-parity-matrix.md from write-parity-template.md. Include one row per standard operation, even when the current slice implements only create/delete.
- Before Java implementation, close focused write probes for the smallest operation slice: valid fixture, invalid payload, missing required fields, duplicate/collision, no permission, missing row, and cleanup/final-count behavior. Store each SQL and output under
oracle-results/.
- Only implement Java write endpoints when all gates for the operation are closed or explicitly deferred for out-of-scope behavior.
- After implementation, run API, OpenAPI/schema, database, and parity checks. For write pilots, run API-level success and negative smokes against Oracle, record request/response JSON, read-after-write behavior, target/side-effect table counts, rollback/no-partial-mutation proof for failed cases, and final zero-count cleanup proof. Keep unsafe operations blocked with explicit HTTP behavior. Include dependency and cleanup parity when delete/update can touch association or generated side-effect tables. Record the applied
praxis-dto-annotations, praxis-java-host-project, and ergon-fieldspec-ui-contract reviews in implementation evidence.
- Before declaring a pilot slice closed, update the parity matrix with exact cases closed by API smoke and exact cases deferred from the pilot. Deferrals must name the operation and reason, such as delete permission requiring a two-user fixture, dependency delete requiring approved dependent-row setup, pending requiring an environment/profile that generates
*_PND, or publication/legal requiring related-component payload capture.
Write Gates
An operation can move to implementation only when all required gates are closed:
- Public key maps to the legacy row or routine input without exposing
ROWID unless explicitly accepted.
- Payload fields map to legacy UI fields and routine/table columns.
- Runtime or source-derived payload evidence proves which fields the legacy UI sends, derives, defaults, or omits for the operation. For standard Cronos
recordPanelEdit + dataTable, XML + Cronos source can close this gate before the DB probe.
- Oracle same-connection session context is implemented when
FLAG_PACK or package state is involved.
- Legacy user/company mapping is centralized and testable; fallback user/company values are explicit and production mapper/resolver hooks are available.
- Permission source is known: HADES access flags, UI capability, Oracle function/package, Java policy, or a combination.
- Trigger/package side effects are known.
- Generated DML procedure behavior is known when the procedure exists, including whether it commits/rolls back internally and whether it matches the screen's route.
- Product and client table rules were audited with
ergon-table-rule-audit for every changed table and side-effect table discovered so far.
- The chosen write path explicitly covers or rejects each active table rule from the audit.
- The table-rule audit includes a product/client execution matrix for each target table phase, including package EPs, trigger EPs, HADES active/inactive branch,
P_MENS, v_ep, and product rules inside/outside IF v_ep THEN.
write-contract.md states whether each phase is product only, client + product, client replaces gated product block, client blocks by P_MENS, inactive, or blocked.
- If Java reimplements behavior, the contract states whether it replaces only the gated product block or also product behavior outside the
v_ep gate.
- If multiple persistence routes exist,
write-route-decision.md marks exactly one route as Chosen, or the operation remains Blocked with the next experiment.
- Direct table/platform persistence is marked
WRITE_TABLE_DIRECT_SAFE only with route coverage, side-effect coverage, HADES/client classification, session context, error mapping, cleanup, and parity evidence.
- Nested dependencies are classified when a rule is reimplemented or orchestrated in Java instead of preserved DB-backed.
- PL/SQL errors and validation messages are mapped to API errors.
- Raw Oracle errors raised by legacy routines are still contract evidence. If probes surface
ORA-06502, ORA-01422, ORA-00001, or similar low-level failures for business-invalid input, map them to stable API errors and add Java pre-validation where appropriate instead of leaking Oracle internals.
- Transaction, rollback, and autonomous transaction behavior are understood.
- The API contract states the transaction boundary, rollback expectation, self-commit/autonomous-transaction risk, cleanup route, and how partial side effects are detected and normalized.
- Parity cases exist for success, invalid input, missing row, duplicate, delete/anulation, pending, and side effects in scope. Permission denial is executed only when a real denied user/profile fixture exists; otherwise record waiver/accepted risk without blocking the screen.
- Controlled fixtures have a cleanup plan that respects legacy-generated dependencies; do not create database test data whose rollback/removal route is unknown.
- For resources migrated read-first, the read resource has backend automated tests and recorded smoke/parity evidence before write endpoints are opened.
- Phase 1.5 has checked whether the write/related operation already exists in the new Java/OMS platform and has chosen reuse, extension, creation, blocking, deferral, or not-api.
- Pilot closure must be evidence-backed: at minimum, record one successful API write/readback/delete cycle, one validation failure with no mutation, one duplicate/collision or equivalent conflict when applicable, one permission denial when a user fixture exists, and explicit deferral rows for everything not in the pilot surface.
- A backend slice can be accepted as partial only when all unimplemented visible operations from the standard set are deliberately blocked or deferred in the contract and parity matrix.
If any gate is open, keep the operation Blocked or Deferred.
Treat payload inferred only from PL/SQL arguments as an open gate. The next action is to return to screen discovery and close payload either through the Cronos source-derived path for standard recordPanelEdit + dataTable, or through browser/debug runtime capture for rotina/object-method/custom actions.
Controlled Probe Discipline
Use disposable fixtures and negative probes before opening write endpoints. For each probe:
- choose a fixture key/date/marker that has zero baseline rows in the target and known side-effect tables;
- before any mutating run, execute a read-only context preflight that proves the selected legacy user, transaction, and empresa context are non-null/valid for side effects reached by the route; if the environment does not provide empresa, discover a valid fixture empresa through the referenced legacy FK/table and record that evidence;
- set
FLAG_PACK on the same connection before invoking the routine, including explicit empresa context when generated triggers/packages call FLAG_PACK.GET_EMPRESA;
- execute the exact candidate route, such as
ERG_DML_*, wrapper routine, or screen-specific package;
- print
call_status, sqlcode, sqlerrm, P_ROWID_REG, P_MENS, and before/after counts;
- include a defensive cleanup path through the same legacy route if the probe unexpectedly creates data;
- commit cleanup explicitly when the legacy route persists beyond caller rollback;
- store both SQL and output under the screen package, using names like
write-invalid-quantity-probe.sql and .out.txt;
- update
plsql-error-map.md and write-parity-matrix.md immediately after each probe.
Do not discard probes that produce raw Oracle errors. A raw ORA-06502 for invalid quantity or ORA-01422 for missing code is a migration finding: the API should pre-validate or translate it into a stable business response while preserving the DB-backed route for valid writes.
For duplicate/collision probes, create the first disposable row through the chosen legacy route, attempt the second row with the same key, record the legacy constraint/message, then delete every marker row through the legacy route and prove final counts are zero.
For permission probes, use a real legacy user/profile fixture when one exists.
A read-denied user can be useful, but write permission must be proven by the
write routine before claiming 403 parity. If no valid denied principal exists,
record a waiver/accepted risk and continue; lack of such fixture must not block
the migrated screen. Do not infer write authorization from UI button state or
read MOSTRA_* alone.
If SQLcl is unreliable in the local environment, use a JDBC PL/SQL runner that enables DBMS_OUTPUT, runs the block on one connection, and writes output to .out.txt. The runner is a test/discovery tool only; production code should use the shared legacy bridge pattern.
API Smoke Discipline
For each implemented write slice, create API result artifacts under docs/migracao/<SCREEN>/api-results/ and Oracle count artifacts under docs/migracao/<SCREEN>/oracle-results/.
Before any mutating API call, run an API smoke preflight and record it as an
artifact. The preflight must prove the local API base URL is alive, the domain
endpoint is protected, a valid authenticated HADES Basic/login session or
cookie is available, and the controlled marker has zero baseline rows in target
and known side-effect tables. Restored Oracle connectivity alone is not API
smoke readiness. If authentication is missing, stop before mutation, record the
auth blocker, and do not mark HTTP parity as closed.
When the migration workspace provides secrets/ergon.env.ps1, dot-source it in
the active shell for local smoke/probe execution. Treat it as the approved local
secret source for variables such as ERGON_HADES_CONN, ERGON_SQLCL,
ERGON_LEGACY_USER, ERGON_LEGACY_PASSWORD, ERGON_RESTRICTED_USER, and
ERGON_RESTRICTED_PASSWORD. Use ERGON_LEGACY_USER/ERGON_LEGACY_PASSWORD
for the positive HADES login preflight and use restricted-user variables only
for permission-denied parity when the case needs a denied fixture. Never print
or persist secret values, session cookies, Authorization headers, or connection
strings; artifacts may record only that the variables were available and which
credential class was used.
Credentials do not authorize mutation by themselves. Before any mutating API
or DB probe, record explicit user approval or an existing gate artifact that
names the screen, resource, disposable marker(s), allowed operations, cleanup
expectation, and exclusions. If approval names a marker such as CX33P5A, use
only that marker and its documented negative variants; do not extend the scope
to real business rows, child resources, dependency fixtures, legal documents,
publications, pending flows, or alternate markers without a new approval.
Record:
- API base URL, legacy user/company/transaction context, and VPN/Oracle connectivity state;
- request JSON for each case;
- response status/body for success, validation, duplicate/conflict, and permission cases;
- public ID returned by create and read-after-write/read-after-delete result;
- before/after counts for target and side-effect tables, including pending tables such as
FREQUENCIAS_PND;
- cleanup route and final zero-count proof.
For permission smokes, run the API with a real denied legacy user fixture or
authenticated principal mapping only when that fixture is available. If the
local app uses fallback properties, it is acceptable for a pilot smoke to start
a temporary API process with a denied ERGON_USUARIO_PADRAO, as long as the
artifact states that this is a local fixture and production auth mapping
remains a separate concern. If no valid denied fixture exists, record waiver
instead of blocking the screen and do not claim proven 403 parity.
Do not leave local API processes running after smoke tests.
Java Implementation Rules
For resources already migrated read-first:
- Reuse existing controller, DTO, FilterDTO, mapper, service, ID converter, endpoint constants, OpenAPI group, and tests when they represent the same resource.
- Match the project's established persistence convention before introducing low-level database access. If the project/starter uses Spring Data/JPA repositories or starter services for writes, prefer that pattern unless the chosen legacy write path requires lower-level same-connection PL/SQL handling and the deviation is documented in
write-route-decision.md.
- When the operation must preserve Oracle package state, triggers, generated DML, or PL/SQL routines, look first for an established project/starter legacy executor or session-context helper. If none exists, recommend or implement a small legacy-backed execution adapter instead of scattering
JdbcTemplate/connection handling across resource services.
- Do not propose a new shared DB-backed command/procedure adapter merely because
multiple services call
ErgonLegacyExecutor. Require
shared-legacy-adapter-evidence.md with at least two distinct
procedure-backed routes approved in Phases 4/5 that prove the same semantic
protocol: registered route identity, operation discriminator, typed internal
payload, OUT/error behavior, same-connection HADES/FLAG_PACK context,
transaction/side effects and cleanup. Direct-table CRUD and one procedure
candidate are not evidence of a reusable command protocol. Until this gate
closes, reuse ErgonLegacyExecutor directly from screen-specific adapters.
- After the two-route gate closes, keep the shared adapter small and generic.
Application services should choose the registered route and bind the payload;
the adapter should delegate to
ErgonLegacyExecutor, execute inside the
correct context, normalize only proven outcomes and reject unknown routes.
- Remove read-only 405 behavior only for operations whose write gates are closed.
- Keep unrelated write operations blocked.
- Avoid making
@Immutable read models mutable unless the resource is intentionally moved away from view-backed reads.
- Prefer a dedicated command DTO for write payloads when response/read DTO contains derived, hidden, view-only, or display-only fields.
- Keep
ROWID internal; if a legacy routine requires it, resolve it server-side from the public key where possible.
- Initialize Oracle session context on the same physical connection used for the write.
- Reuse the shared legacy context provider/resolvers from the read API when available. Do not inject fallback user/company properties directly into each write service.
- Clean up/reset package context before returning pooled connections.
- Keep write routes idempotency-aware at the API boundary. If the legacy route is not idempotent, the contract must state retry behavior and the API smoke must prove duplicate/collision handling before exposing the operation as safe for automated clients.
If any write path requires a new shared legacy bridge, centralize it in the host/runtime layer. Do not encode screen-specific Oracle session handling, HADES user/company mapping, or PL/SQL error normalization separately in each controller/service.
Dependency And Cleanup Parity
For delete/update operations, verify both direct blockers and blockers created transitively by legacy triggers/packages. A code/detail table can generate additional rows in tables such as FINFREQ_*, publication, pending, audit, or company-association tables.
Use controlled fixture data only. Do not test dependency deletes against real business records unless explicitly approved. A dependency parity run should record:
- baseline absence of the f
…(truncated)
1---2name: ergon-archon-write-api-migration3description: Design and implement legacy-backed write APIs for Ergon/Archon screens after screen discovery, read API migration, and table-rule audit gates are closed. Use when Codex must turn write-api-handoff.md, write-risk.md, table-rule audit summaries, and read API artifacts into write contracts, PL/SQL-backed Java endpoints, session-context handling, error mapping, and write parity tests for resources such as ERGadm00033 or ERGadm00189.4metadata:5 source: https://skillmd.com/skills/codexrodrigues/ergon-archon-write-api-migration6---78# Ergon Archon Write API Migration910Use this skill only after screen discovery, read API migration, and required table-rule audits are closed or explicitly deferred. In the current orchestration taxonomy, use `ergon-migration-orchestration` first to confirm the relevant Phase 4/5/6 gate.1112This skill does not rediscover the screen from scratch. It starts from discovery, read API, and table-rule audit artifacts and decides whether write can be implemented safely, preferably by calling existing legacy routines or preserving generated trigger/package behavior instead of reimplementing all business rules in Java.1314This skill must also classify whether a write operation is safe for direct table/platform persistence. Direct Praxis resource persistence is allowed only when the operation reaches `WRITE_TABLE_DIRECT_SAFE`; otherwise use `WRITE_DB_BACKED_REQUIRED`, `WRITE_BLOCKED`, or `WRITE_DEFERRED`.1516When this skill designs or changes command DTOs, request/response DTOs, `@Schema`, `@UISchema`, `@Filterable`, `x-ui`, OpenAPI schemas, `/schemas/filtered`, HATEOAS/action metadata, or capabilities, also use `praxis-dto-annotations` and `ergon-fieldspec-ui-contract`. Use `praxis-java-host-project` when creating or changing a Java/Spring resource. Use `praxis-resource-entity-lookup-backend` when write payloads, actions, or related flows consume `RESOURCE_ENTITY`, `OptionSourceRegistry`, `OptionSourceDescriptor`, or `/option-sources/{sourceKey}`.1718## Platform Governance1920Before designing, exposing, or implementing write metadata, apply the root21migration `AGENTS.md`. Classify the change as `docs-apenas`, `local-pequena`,22`transversal`, `contrato-publico`, or `arquitetural`, and record the canonical23owner in the phase plan/gate.2425Before editing Java, docs, tests, DTOs, resources, or build files, run the26duplicate-module-root guard from `ergon-migration-orchestration` for the target27module/artifactId. A passing unit or parity test in a temporary28`migracao-package` clone is not implementation evidence for the versioned29canonical migration module.3031Do not patch Praxis platform limitations inside the Ergon write endpoint or UI32contract. Before introducing `@WorkflowAction`, `@UiSurface`, capabilities,33availability rules, custom action models, or Angular workarounds, inventory the34native Praxis support and classify the need as `ja-suportado-so-ux`,35`ja-suportado-mal-nomeado-ou-mal-materializado`,36`suportado-parcialmente`, or `lacuna-real-de-contrato`.3738HADES-backed permission and state decisions must remain server-side through39the approved Ergon bridge/starter and canonical Praxis availability extension40points. Public write metadata may expose only availability and public payload,41never HADES, SQL, `ROWID`, empresa, usuario, perfil, package flags, or session42context. Real Praxis gaps must be recorded as `Praxis Platform Follow-up`.4344## Phase Boundary4546Use this as the write API migration skill for the current Phase 4/5/6 sequence: Phase 4 audits write behavior, Phase 5 closes the write contract, and Phase 6 implements approved operations. Older references may call this "Phase 3 - Write API Design"; map that wording to the current taxonomy before deciding gates.47481. `ergon-archon-screen-discovery` anchors the user workflow, XML/runtime SQL, read candidates, and write risk/handoff. It identifies candidate write actions and target routines/tables, but should not guess write parity from names alone.492. `ergon-archon-read-api-migration` closes or implements read/query APIs before write API design. For read-first resources, require backend implementation evidence before write: service/controller tests for the read boundary, explicit blocked-write behavior for inherited generic CRUD, and at least one recorded smoke/parity result or a documented fixture blocker.503. `ergon-archon-write-api-migration` consumes discovery, read API, and table-rule artifacts and closes one write operation at a time. It may implement Java only after target tables, routines, session context, permissions, rules, side effects, and parity cases are closed.514. `ergon-table-rule-audit` is a required Phase 4 input for operations that can write data. Run it after write target tables are known from XML/runtime/handoff evidence and before this skill designs a write contract. Do not use it to replace screen discovery.5253If the handoff does not identify write actions, target tables/routines, public key strategy, payload evidence, session context, operation status, or write blockers, stop and return to `ergon-archon-screen-discovery`. If table-rule audit summaries are missing for any target or side-effect table, return to `ergon-table-rule-audit` unless the operation is explicitly `Blocked`, `Deferred`, or `Not API`.5455## Phase Entry Gate5657Before changing Java, command DTOs, public metadata, or API behavior, create or update the write package with an explicit entry-gate decision:5859- Phase 1/2 discovery artifacts are closed for the operation, including component lineage, operation inventory, API contract, public key strategy, and read/write handoff.60- Phase 3 read API is implemented or explicitly not required for this operation; read-first resources have backend tests, blocked write behavior for unsupported operations, and read smoke/parity evidence.61- Phase 4 table-rule audit is complete for every target and known side-effect table, including HADES `HAD_CAD_SPROC`, `HAD_CAD_MULT_EPS`, `PACK_EXEC_SPROC`, `C_ERGON` routines, generated trigger/package phases, nested dependencies, session context, and cleanup risks.62- The latest `ergon-table-rule-audit` handoff decision is recorded as `Write API safe to design`, `DB-backed write path required`, `Blocked`, or `Deferred`. Only the first two may enter Phase 5 design.63- `praxis-dto-annotations`, `ergon-fieldspec-ui-contract`, and `praxis-java-host-project` reviews are recorded before declaring `Ready for implementation`; `praxis-resource-entity-lookup-backend` is recorded when option sources participate in payloads, duplicate drafts, related resources, or action metadata.64- The operation has a named state: `Required Now`, `Ready for design`, `Ready for implementation`, `Implemented`, `Blocked`, `Deferred`, `Not API`, or `Not present`.6566If any required evidence is missing, do not design a compensating shortcut. Route the work back to the owning phase and record the exact blocker in `write-api-handoff.md` or `write-contract.md`.6768Payload closure is a hard Phase 4/5 input. For standard Cronos69`recordPanelEdit + dataTable`, accept parser-valid XML plus local Cronos70framework source as payload evidence when it proves the route, `_op`, `_p_`,71`_o_`, `_q_p_`, editable fields, table metadata SQL generation, and72same-connection Oracle execution. When73`tools/migration-factory/new-cronos-recordpanel-write-payload.ps1` exists,74require a passing `-Strict` run and generated Markdown/JSON under75`docs/migracao/<SCREEN>/factory/`.7677For rotina/object-method/custom actions, or when XML/source does not prove the78route, the handoff must include browser/debug evidence for the actual payload79produced by the legacy UI, including operation selector, hidden locators,80business fields, publication fields, `P_MENS`, pending/legal/flex fields,81visible confirmation/validation messages, and cancel/no-op behavior. Do not82design command DTOs by copying all PL/SQL arguments when the screen only sends83or derives a subset.8485## Standard Write Operation Set8687For Ergon framework screens, design writes by operation, not by generic CRUD alone. Start with this set and mark each operation as `Implemented`, `Ready`, `Blocked`, `Deferred`, or `Not present`:8889- `Novo/Salvar`: create command, defaults, required fields, legacy route, validation and cleanup.90- `Editar/Salvar`: update command, immutable keys, changed fields, validation and side effects.91- `Apagar`: delete/anulation command, confirmation, permission/dependency blockers, row preservation proof.92- `Duplicar`: copied/defaulted fields, generated key strategy, usually create-route parity but not assumed.93- `Cancelar`: no-mutation proof for create/edit/duplicate modes.94- `Documentos legais`: legal-document read/write route, link key such as `PONTLEI`, component ownership, and whether it is a separate resource.95- `Publicacoes/atos` and `Pendencias`: include when visible or reached by triggers/packages.9697Do not declare a screen's backend "complete" while any visible operation from this set is merely absent from the contract. Either implement it, block it deliberately in the API/UI contract, or defer it with the exact missing evidence and risk.9899## Praxis Write Mapping100101Use the standard Praxis metadata/API resource surface as the API contract, but choose the implementation route by legacy evidence:102103- `Novo/Salvar`: expose `POST /<resource>` and implement through `BaseResourceCommandService.create` only when direct platform persistence is safe. For legacy-generated DML, keep the endpoint but delegate to a screen-specific legacy write service using `ErgonLegacyExecutor`.104- `Editar/Salvar`: expose `PUT /<resource>/{id}` and implement through `BaseResourceCommandService.update`; prefer a command DTO when the read DTO contains derived, hidden, or view-only fields.105- `Apagar`: expose `DELETE /<resource>/{id}` and implement through `BaseResourceCommandService.deleteById`; enable `DELETE /batch` only after separate parity closure.106- `Duplicar`: expose `POST /<resource>/{id}/duplicate-draft` only when the service implements `DuplicateDraftResourceService.duplicateDraft`; use `DuplicateDraftUtils` and `@UISchema(copyOnDuplicate)` for draft behavior, then persist with `POST`. Do not classify duplicate as `@WorkflowAction` merely because the legacy UI has a duplicate button.107- `Cancelar`: do not create a backend mutation; prove no database change from create/edit/duplicate cancellation.108- `Documentos legais`, `Publicacoes/atos`, and `Pendencias`: model as separate related resources/workflows unless the legacy XML/runtime route proves they are part of the main command.109110When writes must preserve Ergon behavior, the Praxis resource method is only the HTTP/resource contract. The implementation must run same-connection `FLAG_PACK` setup/cleanup, call the chosen route (`ERG_DML_*`, screen procedure, direct table with triggers, or writable view), translate Oracle/Ergon errors, reload read DTOs through the public key, and record parity evidence.111112Never create a parallel write contract because the canonical Praxis action/capability model or Ergon legacy bridge is inconvenient. If Praxis lacks an action, availability, schema, option-source, or error-envelope capability needed for a safe Ergon write, classify the platform gap and keep the operation blocked or deferred until the canonical contract is extended.113114Classify every write-like operation against the Praxis semantic contract before exposing metadata:115116- Simple create, update, and delete remain resource operations when Phase 4/5 proves the route is safe.117- Partial same-resource maintenance may use `@ResourceIntent` when it needs a named intent but still belongs to the resource contract.118- Related tabs, read projections, embedded maintenance, legal documents, publications, and pending work are `@UiSurface` or separate related resources unless runtime evidence proves they are part of the same command.119- Business commands such as approve, cancel business state, reopen, publish, generate pending work, or other non-CRUD side-effect operations are `@WorkflowAction`. Duplicate is `@WorkflowAction` only when runtime evidence proves a business command with its own immediate effect, dedicated routine, pending/publication side effect, or semantics beyond preparing an editable create draft; otherwise use `duplicate-draft + POST`.120- Availability should use canonical Praxis capabilities/actions/surfaces. For HADES-backed permission or state decisions, use the existing HADES starter/`HadesLegacyAccessGuard`/legacy bridge plus optional Praxis rules such as `ActionAvailabilityRule`, `SurfaceAvailabilityRule`, and `ResourceStateSnapshotProvider`; do not expose HADES, SQL, `ROWID`, empresa, usuario, or raw session context in public metadata.121122Route safety states:123124- `WRITE_TABLE_DIRECT_CANDIDATE`: direct table/platform persistence may be viable, but evidence is not closed.125- `WRITE_TABLE_DIRECT_SAFE`: direct table/platform persistence is approved for the exact operation. This requires proof that it covers or safely excludes active product/client rules, HADES/EP behavior, package-only logic, side effects, session context, error mapping, transaction behavior, cleanup, and parity.126- `WRITE_DB_BACKED_REQUIRED`: use the validated DB-backed route because direct table persistence would skip or might skip required behavior.127- `WRITE_BLOCKED`: missing or contradictory evidence prevents implementation.128- `WRITE_DEFERRED`: explicitly out of scope.129130Unknown means not safe. If any route coverage, side effect, HADES/client behavior, session context, error precedence, or cleanup path is unknown, do not mark `WRITE_TABLE_DIRECT_SAFE`.131132## Supporting Skills133134Use `ergon-table-rule-audit` before this skill after the write target tables are known. This skill may request additional table audits when operation design reveals side-effect tables not covered in Phase 4.135136Use `praxis-dto-annotations` during Phase 5 contract work before marking command DTOs, request/response DTOs, `@Schema`, `@UISchema`, `@Filterable`, `x-ui`, or `/schemas/filtered` as closed. Use `ergon-fieldspec-ui-contract` to validate schema/action/capability metadata consumed by FieldSpec/Angular. Use `praxis-java-host-project` during Phase 6 implementation before changing resources/controllers/services. Use `praxis-resource-entity-lookup-backend` when governed option sources participate in write payloads, duplicate drafts, related resources, or action metadata.137138It is not a replacement for screen discovery or XML analysis. It is the table-level rule audit used before choosing a write path. Run it for every base table that can be changed by the operation, including association/publication tables reached by triggers or packages.139140Typical examples:141142- `TIPO_FREQ_` and `TIPO_FREQ_EMPRESA` for ERGadm00033 type writes;143- `FREQUENCIAS` and related publication/pending tables for ERGadm00189 frequency writes;144- any table named by `recordPanelEdit dataTable`, generated DML procedure arguments, `INSTEAD OF` view triggers, or package side effects.145146The audit must feed `write-contract.md`, `plsql-error-map.md`, and `write-parity-matrix.md` with:147148- product rules from generated triggers, `PCK_<TABLE>`, `PCK_<TABLE>_PND`, constraints, defaults, and generated DML procedures;149- client rules from `PCK_EXEC_EP_CERG`, HADES `HAD_CAD_SPROC` / `HAD_CAD_MULT_EPS`, and `C_ERGON` routines;150- active/inactive status and execution order;151- the product/client execution matrix for package and trigger phases: `MAIN_PRE`, trigger before, DML/AUX/audit, `MAIN_POS`, and trigger after;152- package EP semantics: `EPB__<TABLE>` and `EPA__<TABLE>` can return `v_ep` plus `P_MENS`; `v_ep = FALSE` can skip only product code inside the relevant `IF v_ep THEN` block;153- trigger EP semantics: `EP_TRG_B_<TABLE>` and `EP_TRG_A_<TABLE>` can block through `P_MENS` but do not return `v_ep` to skip `MAIN_PRE` or `MAIN_POS`;154- product rules explicitly classified as inside or outside the `IF v_ep THEN` gate;155- nested dependency graph when Java may re-orchestrate or reimplement a rule;156- the migration decision for each rule: `Reimplement in Java`, `Keep DB-backed`, `Preserve extension hook`, `Audit/publication only`, or `Out of scope`.157158Save table-rule audit SQL and output under the screen package, preferably:159160```text161docs/migracao/<SCREEN>/oracle-results/table-rule-audit/162 <TABLE>.sql163 <TABLE>.out.txt164 <TABLE>.summary.md165 <TABLE>.nested-dependencies.sql166 <TABLE>.nested-dependencies.out.txt167 <TABLE>.dependency-graph.md168```169170The canonical summary path is `docs/migracao/<SCREEN>/oracle-results/table-rule-audit/<TABLE>.summary.md`. The summary should be short and should contain only findings needed by the write decision, not full trigger/package source dumps. If a root-level `table-rule-audit-<table>.md` exists from exploratory work, link or migrate it into the canonical folder before closing the gate.171172## Required Inputs173174Before using this skill, verify the screen package has:175176- `closure-checklist.md` with screen discovery closed for the intended slice;177- `component-lineage-matrix.md`;178- `api-contract.md`;179- `read-parity-matrix.md` and read implementation/test evidence when reads were implemented;180- `read-parity-results.md` when a read endpoint already exists, including commands/results, smoke fixture, remaining backend parity gaps, and any reason OpenAPI/x-ui checks are still planned;181- `write-risk.md`;182- `write-risk-detail.sql` and Oracle output when database access is available;183- `write-api-handoff.md`;184- `operation-inventory.md` or equivalent operation table listing list/detail/create/update/delete/duplicate/cancel/legal/publication/pending states;185- `platform-reuse-inventory.md` or an equivalent explicit decision showing whether each write/related resource will reuse, extend, create, block, defer, or stay out of the API;186- runtime or source-derived write payload evidence for every operation being designed: for standard Cronos `recordPanelEdit + dataTable`, a passing source-derived payload artifact is acceptable; for other actions use browser/debug payload evidence for `Novo`, `Editar`, `Apagar`, `Duplicar`, `Salvar`, `Cancelar`, or an explicit `Not present` / `Blocked` row;187- for `Duplicar`, a decision proving whether the flow is `duplicate-draft + POST`, a dedicated legacy route, a real `@WorkflowAction`, `Blocked`, or `Not present`; `duplicateEnabled=true` alone is not enough;188- table-rule audit summaries for each target and known side-effect table, unless the operation is not proceeding beyond `Blocked`/`Deferred`;189- implemented read API files when the current state is `Read API implemented`.190191If these are missing, return to the owning earlier phase instead of guessing write behavior: use `ergon-archon-screen-discovery` for missing lineage/handoff, `ergon-archon-read-api-migration` for missing read implementation or read parity evidence, and `ergon-table-rule-audit` for missing table-rule evidence.192193## Core Strategy194195Prefer `Legacy-backed Write API` when possible:196197- Java owns REST contract, authentication, authorization checks, payload validation, session context setup, transaction boundary, and error mapping.198- Oracle legacy routines, generated DML, triggers, and packages preserve business behavior.199- Java reimplementation is allowed only when the legacy routine is unsuitable and all validations, side effects, and parity cases are fully understood.200201Do not expose generic CRUD merely because `AbstractResourceController` has create/update/delete hooks.202203Do expose direct platform/table CRUD when, and only when, `write-route-decision.md` marks the operation `WRITE_TABLE_DIRECT_SAFE` and parity evidence supports it. This is a speed path, not a shortcut around rule audit.204205## Legacy Bridge Pattern206207When a migrated service must talk to legacy write behavior for years while the full flow remains split between Java and Oracle, prefer a small shared bridge over ad hoc database calls in each resource.208209The bridge should centralize:210211- same-connection legacy context setup such as `HADES.FLAG_PACK.SET_USUARIO`, `SET_TRANSACAO`, `SET_EMPRESA`, and optional `SET_SIS`/`SET_ROLE`;212- legacy user and company mapping through shared application hooks, such as `ErgonLegacyContextProvider`, `ErgonLegacyUserMapper`, and `ErgonLegacyCompanyResolver` in `ms-administracao-pessoal`, so production IdP/company-session differences are not reimplemented per write service;213- transaction participation and cleanup/reset for pooled connections;214- invocation of the chosen route: generated `ERG_DML_*`, direct table DML with generated triggers, writable view, or specific PL/SQL package;215- translation of `ORA-20xxx`, HADES/Ergon validation messages, unique violations, dependency violations, and setup failures into stable API errors;216- operation metadata: screen/transaction, company, user, route name, and evidence links.217218If no existing Praxis host/shared module already provides this capability, create or extend a runtime-neutral legacy bridge only when it stays independent of UI/editor code and does not import a business module. Keep screen-specific DML, SQL text, DTO mapping, and policy decisions in the application module.219220Do not make `JdbcTemplate` the declared project standard just because the bridge uses JDBC internally. First inspect the target module and starter conventions. If the module uses Spring Data/JPA plus a starter, keep resource/service/repository code aligned with that convention and confine low-level JDBC to a shared executor only when same-connection package state or callable PL/SQL requires it. Document the deviation in `write-route-decision.md`.221222## Workflow2232241. Read `write-api-handoff.md`, `write-risk.md`, `api-contract.md`, `platform-reuse-inventory.md`, and the read implementation files.2252. Identify the write resource, operations, public key strategy, current read DTO, and UI write buttons using the Standard Write Operation Set.2263. Inspect the Java project convention before selecting a persistence mechanism: existing write resources, starter-provided services/repositories, Spring Data/JPA repositories, `EntityManager`, transaction/session helpers, and any project abstraction for calling PL/SQL or generated DML. If Phase 1.5 found an existing resource, prefer reusing/extending it over creating a parallel endpoint. Do not assume `JdbcTemplate` is the default merely because direct Oracle calls are needed. If no shared helper exists and same-connection package state is required, propose or implement a legacy bridge abstraction instead of scattering low-level JDBC.2274. Inspect the Archon XML write component: `recordPanelEdit`, `dataTable`, `db:*` routine, duplicate behavior, delete/anulacao behavior, linked publication/legal blocks, and hidden row keys.2285. Inspect Oracle metadata for target tables, generated DML routines, triggers, grants, constraints, defaults, packages, package arguments, and source references.2296. Run `ergon-table-rule-audit` for each write target base table and each side-effect table that can be reached by triggers/packages.2307. Convert table-rule audit findings into an operation-level product/client decision matrix. For each phase (`MAIN_PRE`, trigger before, DML/AUX/audit, `MAIN_POS`, trigger after), classify the result as `product only`, `client + product`, `client replaces gated product block`, `client blocks by P_MENS`, `inactive`, or `unknown/blocked`. Identify product rules inside and outside `IF v_ep THEN`.2318. Convert the matrix into operation-level decisions: which rules are covered by the chosen legacy write path, which require Java behavior, which are audit/publication only, which preserve a customer extension hook, and which are out of scope for this operation.2329. If more than one persistence route exists, produce `write-route-decision.md` from [write-route-decision-template.md](references/write-route-decision-template.md). Do not ask the developer to choose manually. Compare generated `ERG_DML_*`, direct base-table DML, writable view triggers, and screen-specific PL/SQL packages against the same fixture whenever possible.23310. Decide the write strategy for each operation: `legacy-routine`, `direct-table-with-triggers`, `writable-view`, `java-reimplementation`, `blocked`, or `not-api`.234 Also record route safety state: `WRITE_TABLE_DIRECT_SAFE`, `WRITE_DB_BACKED_REQUIRED`, `WRITE_BLOCKED`, or `WRITE_DEFERRED`.23511. Produce `write-contract.md` from [write-contract-template.md](references/write-contract-template.md). Include the product/client decision matrix in the contract or link to the canonical table-rule audit summary that contains it. Record the applied `praxis-dto-annotations` and `ergon-fieldspec-ui-contract` review before marking Phase 5 ready.23612. Produce `plsql-error-map.md` from [plsql-error-map-template.md](references/plsql-error-map-template.md).23713. Produce `write-parity-matrix.md` from [write-parity-template.md](references/write-parity-template.md). Include one row per standard operation, even when the current slice implements only create/delete.23814. Before Java implementation, close focused write probes for the smallest operation slice: valid fixture, invalid payload, missing required fields, duplicate/collision, no permission, missing row, and cleanup/final-count behavior. Store each SQL and output under `oracle-results/`.23915. Only implement Java write endpoints when all gates for the operation are closed or explicitly deferred for out-of-scope behavior.24016. After implementation, run API, OpenAPI/schema, database, and parity checks. For write pilots, run API-level success and negative smokes against Oracle, record request/response JSON, read-after-write behavior, target/side-effect table counts, rollback/no-partial-mutation proof for failed cases, and final zero-count cleanup proof. Keep unsafe operations blocked with explicit HTTP behavior. Include dependency and cleanup parity when delete/update can touch association or generated side-effect tables. Record the applied `praxis-dto-annotations`, `praxis-java-host-project`, and `ergon-fieldspec-ui-contract` reviews in implementation evidence.24117. Before declaring a pilot slice closed, update the parity matrix with exact cases closed by API smoke and exact cases deferred from the pilot. Deferrals must name the operation and reason, such as delete permission requiring a two-user fixture, dependency delete requiring approved dependent-row setup, pending requiring an environment/profile that generates `*_PND`, or publication/legal requiring related-component payload capture.242243## Write Gates244245An operation can move to implementation only when all required gates are closed:246247- Public key maps to the legacy row or routine input without exposing `ROWID` unless explicitly accepted.248- Payload fields map to legacy UI fields and routine/table columns.249- Runtime or source-derived payload evidence proves which fields the legacy UI sends, derives, defaults, or omits for the operation. For standard Cronos `recordPanelEdit + dataTable`, XML + Cronos source can close this gate before the DB probe.250- Oracle same-connection session context is implemented when `FLAG_PACK` or package state is involved.251- Legacy user/company mapping is centralized and testable; fallback user/company values are explicit and production mapper/resolver hooks are available.252- Permission source is known: HADES access flags, UI capability, Oracle function/package, Java policy, or a combination.253- Trigger/package side effects are known.254- Generated DML procedure behavior is known when the procedure exists, including whether it commits/rolls back internally and whether it matches the screen's route.255- Product and client table rules were audited with `ergon-table-rule-audit` for every changed table and side-effect table discovered so far.256- The chosen write path explicitly covers or rejects each active table rule from the audit.257- The table-rule audit includes a product/client execution matrix for each target table phase, including package EPs, trigger EPs, HADES active/inactive branch, `P_MENS`, `v_ep`, and product rules inside/outside `IF v_ep THEN`.258- `write-contract.md` states whether each phase is `product only`, `client + product`, `client replaces gated product block`, `client blocks by P_MENS`, `inactive`, or `blocked`.259- If Java reimplements behavior, the contract states whether it replaces only the gated product block or also product behavior outside the `v_ep` gate.260- If multiple persistence routes exist, `write-route-decision.md` marks exactly one route as `Chosen`, or the operation remains `Blocked` with the next experiment.261- Direct table/platform persistence is marked `WRITE_TABLE_DIRECT_SAFE` only with route coverage, side-effect coverage, HADES/client classification, session context, error mapping, cleanup, and parity evidence.262- Nested dependencies are classified when a rule is reimplemented or orchestrated in Java instead of preserved DB-backed.263- PL/SQL errors and validation messages are mapped to API errors.264- Raw Oracle errors raised by legacy routines are still contract evidence. If probes surface `ORA-06502`, `ORA-01422`, `ORA-00001`, or similar low-level failures for business-invalid input, map them to stable API errors and add Java pre-validation where appropriate instead of leaking Oracle internals.265- Transaction, rollback, and autonomous transaction behavior are understood.266- The API contract states the transaction boundary, rollback expectation, self-commit/autonomous-transaction risk, cleanup route, and how partial side effects are detected and normalized.267- Parity cases exist for success, invalid input, missing row, duplicate, delete/anulation, pending, and side effects in scope. Permission denial is executed only when a real denied user/profile fixture exists; otherwise record waiver/accepted risk without blocking the screen.268- Controlled fixtures have a cleanup plan that respects legacy-generated dependencies; do not create database test data whose rollback/removal route is unknown.269- For resources migrated read-first, the read resource has backend automated tests and recorded smoke/parity evidence before write endpoints are opened.270- Phase 1.5 has checked whether the write/related operation already exists in the new Java/OMS platform and has chosen reuse, extension, creation, blocking, deferral, or not-api.271- Pilot closure must be evidence-backed: at minimum, record one successful API write/readback/delete cycle, one validation failure with no mutation, one duplicate/collision or equivalent conflict when applicable, one permission denial when a user fixture exists, and explicit deferral rows for everything not in the pilot surface.272- A backend slice can be accepted as partial only when all unimplemented visible operations from the standard set are deliberately blocked or deferred in the contract and parity matrix.273274If any gate is open, keep the operation `Blocked` or `Deferred`.275276Treat payload inferred only from PL/SQL arguments as an open gate. The next action is to return to screen discovery and close payload either through the Cronos source-derived path for standard `recordPanelEdit + dataTable`, or through browser/debug runtime capture for rotina/object-method/custom actions.277278## Controlled Probe Discipline279280Use disposable fixtures and negative probes before opening write endpoints. For each probe:281282- choose a fixture key/date/marker that has zero baseline rows in the target and known side-effect tables;283- before any mutating run, execute a read-only context preflight that proves the selected legacy user, transaction, and empresa context are non-null/valid for side effects reached by the route; if the environment does not provide empresa, discover a valid fixture empresa through the referenced legacy FK/table and record that evidence;284- set `FLAG_PACK` on the same connection before invoking the routine, including explicit empresa context when generated triggers/packages call `FLAG_PACK.GET_EMPRESA`;285- execute the exact candidate route, such as `ERG_DML_*`, wrapper routine, or screen-specific package;286- print `call_status`, `sqlcode`, `sqlerrm`, `P_ROWID_REG`, `P_MENS`, and before/after counts;287- include a defensive cleanup path through the same legacy route if the probe unexpectedly creates data;288- commit cleanup explicitly when the legacy route persists beyond caller rollback;289- store both SQL and output under the screen package, using names like `write-invalid-quantity-probe.sql` and `.out.txt`;290- update `plsql-error-map.md` and `write-parity-matrix.md` immediately after each probe.291292Do not discard probes that produce raw Oracle errors. A raw `ORA-06502` for invalid quantity or `ORA-01422` for missing code is a migration finding: the API should pre-validate or translate it into a stable business response while preserving the DB-backed route for valid writes.293294For duplicate/collision probes, create the first disposable row through the chosen legacy route, attempt the second row with the same key, record the legacy constraint/message, then delete every marker row through the legacy route and prove final counts are zero.295296For permission probes, use a real legacy user/profile fixture when one exists.297A read-denied user can be useful, but write permission must be proven by the298write routine before claiming `403` parity. If no valid denied principal exists,299record a waiver/accepted risk and continue; lack of such fixture must not block300the migrated screen. Do not infer write authorization from UI button state or301read `MOSTRA_*` alone.302303If SQLcl is unreliable in the local environment, use a JDBC PL/SQL runner that enables `DBMS_OUTPUT`, runs the block on one connection, and writes output to `.out.txt`. The runner is a test/discovery tool only; production code should use the shared legacy bridge pattern.304305## API Smoke Discipline306307For each implemented write slice, create API result artifacts under `docs/migracao/<SCREEN>/api-results/` and Oracle count artifacts under `docs/migracao/<SCREEN>/oracle-results/`.308309Before any mutating API call, run an API smoke preflight and record it as an310artifact. The preflight must prove the local API base URL is alive, the domain311endpoint is protected, a valid authenticated HADES Basic/login session or312cookie is available, and the controlled marker has zero baseline rows in target313and known side-effect tables. Restored Oracle connectivity alone is not API314smoke readiness. If authentication is missing, stop before mutation, record the315auth blocker, and do not mark HTTP parity as closed.316317When the migration workspace provides `secrets/ergon.env.ps1`, dot-source it in318the active shell for local smoke/probe execution. Treat it as the approved local319secret source for variables such as `ERGON_HADES_CONN`, `ERGON_SQLCL`,320`ERGON_LEGACY_USER`, `ERGON_LEGACY_PASSWORD`, `ERGON_RESTRICTED_USER`, and321`ERGON_RESTRICTED_PASSWORD`. Use `ERGON_LEGACY_USER`/`ERGON_LEGACY_PASSWORD`322for the positive HADES login preflight and use restricted-user variables only323for permission-denied parity when the case needs a denied fixture. Never print324or persist secret values, session cookies, Authorization headers, or connection325strings; artifacts may record only that the variables were available and which326credential class was used.327328Credentials do not authorize mutation by themselves. Before any mutating API329or DB probe, record explicit user approval or an existing gate artifact that330names the screen, resource, disposable marker(s), allowed operations, cleanup331expectation, and exclusions. If approval names a marker such as `CX33P5A`, use332only that marker and its documented negative variants; do not extend the scope333to real business rows, child resources, dependency fixtures, legal documents,334publications, pending flows, or alternate markers without a new approval.335336Record:337338- API base URL, legacy user/company/transaction context, and VPN/Oracle connectivity state;339- request JSON for each case;340- response status/body for success, validation, duplicate/conflict, and permission cases;341- public ID returned by create and read-after-write/read-after-delete result;342- before/after counts for target and side-effect tables, including pending tables such as `FREQUENCIAS_PND`;343- cleanup route and final zero-count proof.344345For permission smokes, run the API with a real denied legacy user fixture or346authenticated principal mapping only when that fixture is available. If the347local app uses fallback properties, it is acceptable for a pilot smoke to start348a temporary API process with a denied `ERGON_USUARIO_PADRAO`, as long as the349artifact states that this is a local fixture and production auth mapping350remains a separate concern. If no valid denied fixture exists, record waiver351instead of blocking the screen and do not claim proven `403` parity.352353Do not leave local API processes running after smoke tests.354355## Java Implementation Rules356357For resources already migrated read-first:358359- Reuse existing controller, DTO, FilterDTO, mapper, service, ID converter, endpoint constants, OpenAPI group, and tests when they represent the same resource.360- Match the project's established persistence convention before introducing low-level database access. If the project/starter uses Spring Data/JPA repositories or starter services for writes, prefer that pattern unless the chosen legacy write path requires lower-level same-connection PL/SQL handling and the deviation is documented in `write-route-decision.md`.361- When the operation must preserve Oracle package state, triggers, generated DML, or PL/SQL routines, look first for an established project/starter legacy executor or session-context helper. If none exists, recommend or implement a small legacy-backed execution adapter instead of scattering `JdbcTemplate`/connection handling across resource services.362- Do not propose a new shared DB-backed command/procedure adapter merely because363 multiple services call `ErgonLegacyExecutor`. Require364 `shared-legacy-adapter-evidence.md` with at least two distinct365 procedure-backed routes approved in Phases 4/5 that prove the same semantic366 protocol: registered route identity, operation discriminator, typed internal367 payload, OUT/error behavior, same-connection HADES/`FLAG_PACK` context,368 transaction/side effects and cleanup. Direct-table CRUD and one procedure369 candidate are not evidence of a reusable command protocol. Until this gate370 closes, reuse `ErgonLegacyExecutor` directly from screen-specific adapters.371- After the two-route gate closes, keep the shared adapter small and generic.372 Application services should choose the registered route and bind the payload;373 the adapter should delegate to `ErgonLegacyExecutor`, execute inside the374 correct context, normalize only proven outcomes and reject unknown routes.375- Remove read-only 405 behavior only for operations whose write gates are closed.376- Keep unrelated write operations blocked.377- Avoid making `@Immutable` read models mutable unless the resource is intentionally moved away from view-backed reads.378- Prefer a dedicated command DTO for write payloads when response/read DTO contains derived, hidden, view-only, or display-only fields.379- Keep `ROWID` internal; if a legacy routine requires it, resolve it server-side from the public key where possible.380- Initialize Oracle session context on the same physical connection used for the write.381- Reuse the shared legacy context provider/resolvers from the read API when available. Do not inject fallback user/company properties directly into each write service.382- Clean up/reset package context before returning pooled connections.383- Keep write routes idempotency-aware at the API boundary. If the legacy route is not idempotent, the contract must state retry behavior and the API smoke must prove duplicate/collision handling before exposing the operation as safe for automated clients.384385If any write path requires a new shared legacy bridge, centralize it in the host/runtime layer. Do not encode screen-specific Oracle session handling, HADES user/company mapping, or PL/SQL error normalization separately in each controller/service.386387## Dependency And Cleanup Parity388389For delete/update operations, verify both direct blockers and blockers created transitively by legacy triggers/packages. A code/detail table can generate additional rows in tables such as `FINFREQ_*`, publication, pending, audit, or company-association tables.390391Use controlled fixture data only. Do not test dependency deletes against real business records unless explicitly approved. A dependency parity run should record:392393- baseline absence of the f394395…(truncated)