# Praxis Java Availability Discovery Authoring

> Praxis Java Availability Discovery Authoring

- Skill: `codexrodrigues/praxis-java-availability-discovery-authoring` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx get-skill add codexrodrigues/praxis-java-availability-discovery-authoring`
- Raw SKILL.md: https://api.skillmd.com/api/skills/codexrodrigues/praxis-java-availability-discovery-authoring/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: codexrodrigues (https://skillmd.com/u/codexrodrigues)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/codexrodrigues/praxis-java-availability-discovery-authoring

---


# Praxis Java Availability Discovery Authoring

Author discovery from executable resource operations. A surface describes a
composed business experience; an action describes an explicit command;
capabilities aggregate availability over those contracts. None of them is a
second schema, a button registry, or a frontend visibility workaround.

## Establish The Executable Operation

Inspect the resource key/path, controller method, request/response schema,
service state transition, authorization, entity/view state, existing actions and
surfaces, capabilities snapshot, direct runtime consumer, and focused tests.
Decide whether the need is collection or item scoped, ordinary CRUD, explicit
business command, composed journey, related-resource navigation, stats, export,
or only a runtime materialization gap.

Classify every proposed surface, action, availability input, capability field,
related resource, or catalog shape as `ja-suportado-so-ux`,
`ja-suportado-mal-nomeado-ou-mal-materializado`,
`suportado-parcialmente`, or `lacuna-real-de-contrato`. Do not add discovery
metadata until an actual operation and its canonical schema exist.

## Author Discovery And Availability

1. Keep ordinary create/read/update/delete on the resource baseline. Model a
   stateful or consequential business command as `@WorkflowAction`, with stable
   action ID, scope, input/output schemas, side effect, state and authorization
   conditions, HTTP outcome, and negative path. Do not conceal it in a generic
   PATCH/PUT or infer it from a method name.
2. Model a composed journey as `@UiSurface` over real operations and canonical
   schemas. State its scope, target resource/child binding, supported operations,
   and materialization purpose. Do not use a surface merely to name a route,
   drawer, tab, or button.
3. Keep `@UiSurface` and `@WorkflowAction` separate. Combining them on one
   method enters an explicit conflict-validation zone and requires a documented
   reason plus validation of `praxis.metadata.validation.*` behavior.
4. Define availability from a shared `ResourceStateSnapshot` and contextual
   availability resolvers/evaluators. `DefaultCapabilityService` opens a
   `ResourceStateSnapshotScope` per item capability projection so surface,
   action, and capability resolvers share a single
   `ResourceStateSnapshotProvider.resolve(resourceKey, resourceId)` lookup.
   Whenever a controller declares `allowedStates` on `@WorkflowAction` or
   `@UiSurface`, register that `@ApiResource(resourceKey = ...)` in the host's
   `ResourceStateSnapshotProvider` (e.g. `QuickstartResourceStateSnapshotProvider`)
   and cover it with an architectural test so item `/capabilities` never degrades
   to `SNAPSHOT_UNAVAILABLE`. Do not add repeated N+1 loads or duplicate state
   predicates in controllers and Angular.
5. Preserve the distinction between absent catalog entry and unavailable
   capability. Catalogs report definitions; `GET /{resource}/capabilities` and
   `GET /{resource}/{id}/capabilities` publish aggregate collection/item snapshots.
   They do not redefine request payloads, schemas, or business rules.
6. Add related-resource surfaces only when child binding and child operations are
   backed by canonical child capabilities (`SurfaceCatalogService` memoizes child
   capability lookups per normalized `childResourcePath` within each catalog pass).
   Add stats/export only when actual `StatsFieldRegistry` / `StatsSupportMode` or
   collection export support exists.
7. Keep `RestApiResponse._links` aligned with available operations. Do not replace
   HATEOAS with host-local link fields or force the UI to rebuild URLs from labels.

Read [discovery-decision-matrix.md](references/discovery-decision-matrix.md)
when selecting discovery type, scope, availability evidence, or focused proof.

## Bind An Explicit Operation Safely

When a contract references an operation by ID, inspect the exact Metadata version's
`CanonicalOperationResolver` and `docs/spec/CANONICAL-OPERATION-BINDING.md` first.
Where available, `requireResourceOperation(resourceKey, operationId, method)` checks
an explicit `@Operation` against the real MVC registration and matching `@ApiResource`.
Use it after handler initialization; do not reconstruct this proof in the host or
choose a handler by path fragments. Custom resolvers must implement the strict
method; its default throws rather than falling back to permissive lookup.

Global uniqueness is checked before resource/method filtering, including collisions
with effective legacy Java method IDs. `resolveByOperationId` rejects duplicate IDs;
its legacy single-handler fallback is not a strict binding. Require one path and
method; reject an address shared by another mapping even with a different ID or
media type. Reject hidden or unrepresentable conditional routing, and do not silently
normalize a different registered path.

For a governed bulk business action, keep the confirmation as a real
`@WorkflowAction` and bind it with `@BulkOperation` on that same handler. The
controller must also declare `@BulkResourceOperations`; its five IDs bind only
the shared lifecycle handlers, while `@BulkOperation` binds the business
confirmation/evaluation pair. The method annotation names the bulk mode, the
distinct evaluation `operationId`, and the collection atomicity. Both confirmation
and evaluation must be explicit POST operations in the same `@ApiResource` controller,
with request bodies and globally unique operation IDs; the declared atomicity must
agree with the workflow action. An action annotation without the class-level
lifecycle declaration is orphaned: the binding diagnostic must reserve its IDs and
strict operation resolution must fail closed. Do not treat evaluation or
confirmation as a bodyless lifecycle operation.

The binding proves identity between real MVC handlers; it does not prove complete
OpenAPI schema content, evaluation-provider wiring, authorization, descriptor
fingerprint, durable lifecycle control, readiness, or execution. A missing or
ambiguous pair must fail closed as a whole. For the structural composition step,
the five lifecycle operations must also prove absence of OpenAPI `requestBody` in
the captured group snapshot with `snapshot.requireNoRequestBody(operation)`.

## Bind The Actual MVC Request DTO

Where available, use `requireResourceRequestBody(resourceKey, operationId, method,
mapper.getTypeFactory())` and read `docs/spec/CANONICAL-OPERATION-BINDING.md` first.
It shares the strict MVC entry with operation resolution and returns operation plus
`JavaType` from the actual required `@RequestBody`, resolving controller/interface
generics. Do not pass an independently guessed DTO or perform another handler lookup
in the host.

Only the documented concrete DTO subset is supported. Reject optional/multiple bodies,
transport wrappers, scalar/container roots, raw/unbound/wildcard types, non-static member
classes and unresolved generic ancestors. Pass the returned operation to
`documents.requireRequestSchema` and the returned `bodyType` to `BulkEditableFields`
with the same configured mapper and trusted protected wire names.

## Preserve The Platform Boundary

- `praxis-metadata-starter` owns annotations, catalogs, availability
  contexts/evaluators, resource state snapshots, capabilities, HATEOAS, and
  stats/export discovery.
- The host owns verified domain state, command implementation, authorization, and
  snapshot provider inputs. It must not create a separate action catalog or
  availability vocabulary.
- `praxis-ui-angular` consumes catalog/capability projections. It must not decide
  availability from labels, role-name strings, local regexes, or copied states.

Do not resolve primary user intent or choose an action/surface from keywords,
aliases, fuzzy matching, or route fragments. Use resource keys, action IDs,
surface IDs, schemas, capabilities, and governed context; text can only rank
already scoped candidates.

## Prove The Full Discovery Path

Prove definition, scope, positive availability, negative availability, correct
schemas, capability projection, and direct consumer materialization. For an item
decision, prove the state snapshot is shared instead of repeatedly loaded. For a
workflow action, prove execution and rejection in invalid state or authorization.
For related resources, prove binding and child capability alignment.

Use focused action, surface, capability, HATEOAS, stats/export, and cockpit tests
from the starter. Add quickstart HTTP/cockpit proof for public contracts and
review Angular action/surface/resource runtime tests. Review docs or HTTP examples
only when their published catalog/capability claim changes.

## Companion Skills

- `praxis-java-resource-authoring`: operations, resource hierarchy, DTOs, and proof.
- `praxis-metadata-discovery-capabilities`: canonical discovery, availability,
  capabilities, cockpit, stats, and export behavior.
- `praxis-metadata-schema-contracts`: operation schemas and filtered schema.
- `praxis-metadata-resource-baseline`: resource base, `_links`, query, export,
  and stats foundations.
- `praxis-api-quickstart-cockpit-http-validation`: published HTTP/cockpit proof.

Close with the operation-to-discovery matrix, snapshot inputs, availability
decisions, positive/negative evidence, consumer proof, and any platform gap.
Discovery is ready when the runtime can determine what is possible and why,
without reconstructing business semantics locally.

