Praxis Java Quickstart Proof
Treat Quickstart as an operational proof host, never the owner of starter semantics.
Choose one representative resource and prove a canonical path by HTTP with fixtures
that demonstrate both success and an important negative condition.
Build The Proof Slice
Inspect ApiPaths, controller, service, DTO/filter/action, mapper, option source,
test fixtures, security/origin setup, and existing pilot integration tests. Reuse
an existing pilot when it proves the same capability; do not copy a domain only
to make a new example. Fix a starter gap in the starter, then add the smallest
downstream proof here.
Required Evidence
- Prove resource identity in OpenAPI and
/schemas/filtered, including stable
path/resource key, request/response operation schemas, x-ui, ETag and hash.
- Exercise each published operation in scope: filter/read, lookup reload,
action/surface/capabilities, stats/export, or write. Verify
_links and
collection/item discovery agree.
- Include a negative case: invalid payload, missing resource, denied state,
invalid filter/option request, conflict, or policy limit. Prove no mutation
follows a rejected write.
- For database-backed proof, use explicitly assigned isolated Neon branches;
unit tests without a database may run locally. For writes, retain controlled
fixtures, read-after-write, side-effect evidence and cleanup. Do not substitute
H2, embedded/local PostgreSQL or an unassigned parent/production branch.
- Run the relevant
QuickstartMetadataMigrationIntegrationTest,
EventosFolhaPilotIntegrationTest, focused pilot test, or Cockpit verifier.
Review direct Angular runtime proof when the published contract changes.
Read proof-slice-matrix.md when selecting
the smallest representative resource and required evidence.
Before provisioning, distinguish no-database checks, still-valid evidence,
reattestation of the current exclusive campaign and a necessary new physical
branch. A new source/phase/retry/release does not by itself require a new branch.
Campaign means one bounded active test/suite execution: create just in time and
physically delete immediately after its last use, including failure/cancellation,
not per test method and not retained across idle sessions or pending PRs. Keep
sanitized receipts, not old branches for later restoration. The provisioner owns
control-plane closure, including failure before runner materialization; fixture
cleanup and always() do not certify branch deletion. Native TTL is only a
cleanup-failure backstop; uncertain deletion needs reconciliation and no false
success. Respect tool confirmation and scope; never delete parent/production.
Follow the workspace AGENTS branch lifecycle: bind project/branch IDs, exclusive
owner, purpose, baseline and fixed custody deadline; each attempt still needs its
own current source/dependencies and gate-valid assignment. Sequential reuse needs
closed prior connections, reconciled effects, proven fixture cleanup and required
initial state, fresh control-plane/PG/TLS/privilege observation. Never share across
concurrent workers or replace a required virgin clone with logical cleanup.
Set and read back native expires_at before SQL/host startup, normally within
48 hours for the campaign including transitions/cleanup; execution leases must fit
that fixed authorized custody. No rolling extension per retry. A local assignment
expiry does not delete the Neon branch. Use a designated durable baseline and an
independent leaf per concurrent campaign: Neon rejects TTL on parents,
default/protected branches and children of expiring parents. Do not remove TTL or
reuse a shared database to bypass this. After campaign completion, definitive
failure or cancellation, close owned hosts/connections and perform authorized
physical branch cleanup with readback; uncertain outcomes block serial reuse;
keep native TTL as the failure backstop. Preserve referenced fixtures, backups
and other workers' reservations; exceptions need IDs, current need, owner and
review deadline. Historical pins or a prior hold do not establish perpetual need.
See the official
expiration restrictions.
Focal Proof And The Integral Neon Gate
A focused pilot proves its selected behavior. It does not accept the host's
integral release gate, even when its Maven goal is verify. For starter adoption,
bootstrap or packaging changes that require the wider gate, follow the existing
praxis-api-quickstart-operational-proof procedure.
Verify the final private source and generated sanitized tree in sequence against
the same public coordinates, with separately attributable reports and cleanup.
Retain every required test and its assertions. Inventory optional cases by exact
class/method, existing opt-in condition and reason; report skipped/aborted cases
by name rather than accepting a total alone. Optional lanes outside the selected
gate remain explicitly unproved. Missing assignment, new exclusions, disabled
tests or an empty selection cannot produce a passing database proof. Keep raw
logs, credentials and failure reports private until their export is reviewed;
publish only the closed, sanitized evidence projection.
Published SDK Adoption On Neon
Inspect the Quickstart POM, src/test/java/com/example/praxis/apiquickstart/config/MetadataAdoptionNeonFixture.java,
its unit tests, src/test/resources/metadata-adoption/neon-fixture.sql, and the three
Metadata downstream pilots before selecting this gate. This route proves host
consumption of published SDKs; it does not publish an SDK or release the host.
- Verify the public POM/JAR bytes first, then adopt the published coordinates in
the host POM. Resolve through
.mvn/ql07-central-only-settings.xml and a fresh
isolated Maven repository. Do not use a local SDK install, candidate GAV or
praxis.core.version/praxis.config.version override as public-adoption proof.
- Inspect the current
MetadataAdoptionNeonFixture and
config/neon/AssignedNeonStores: the reviewed PR #482 fixture uses the shared
Quickstart assignment, not the historical three-file adoption lease. Follow
the integral gate's assignment procedure
to bind PRAXIS_QUICKSTART_NEON_ASSIGNMENT_FILE, its SHA-256, run ID,
expected repository and source SHA. Confirm the target checkout contains this
fixture before executing; do not apply candidate guidance to an older release.
Keep credential files private and outside source/artifacts. Never copy
passwords/DSNs into guidance, manifests, reports or command arguments, or reuse
historical endpoint/expiry values. Serialize classes sharing the SDK roles.
- Confirm endpoint/TLS/PostgreSQL identity and actual role privileges before
mutation. Owner may prepare and remove only assigned fixture databases/roles. The application
uses ordinary API and Config runtimes: neither may be superuser, bypass RLS,
create roles/databases, or be a member of
neondb_owner/neon_superuser and
assume those roles. Direct privilege flags alone do not prove this separation.
- Enable the official external-test opt-in, retain all selected cases and use
the host's published POM without overrides. From the Quickstart checkout, with
the assignment inputs exported and an absolute fresh repository path in
PRAXIS_ADOPTION_MAVEN_REPO:
: "${PRAXIS_ADOPTION_MAVEN_REPO:?Set an absolute fresh isolated Maven repository}"
PRAXIS_EXTERNAL_SMOKE_TESTS=true mvn -B -ntp \
-s .mvn/ql07-central-only-settings.xml \
"-Dmaven.repo.local=$PRAXIS_ADOPTION_MAVEN_REPO" \
-Dtest=OpenApiGroupResolutionIsolatedIntegrationTest,QuickstartMetadataMigrationIntegrationTest,EventosFolhaPilotIntegrationTest \
-Dsurefire.failIfNoSpecifiedTests=true verify
Require the reviewed selection's full case count and zero failures, errors and
skips (currently 43 cases across these three classes). Missing inputs must fail
closed; an opt-in-disabled/skipped run is not a proof. Bind raw reports, source
and SQL hashes, resolved public dependency bytes and packaged dependencies to
this exact run and child assignment.
If a failed assertion is corrected without changing production source, dependencies,
shared fixtures or the passing classes, rerun the affected class with separate
reports after verified cleanup. Reuse the cache only when its exclusively public
origin remains proven. Preserve the negative run and compare source/dependency
hashes before retaining earlier passes. Require the complete case matrix to pass;
label combined evidence explicitly rather than claiming a single green 43-case
run. Changes to shared fixtures or runtime behavior invalidate the affected prior
passes and require those cases to run again.
Use the official bootstrap and migrations on the assigned databases. The
financial fixture must activate approved governance through the real Config
publication path and write payroll/events through admitted HTTP actions; SQL
inserts into those governed aggregates cannot replace that authority. Scope
nonfinancial seed and assertions to unique case IDs, including unique text keys.
Preserve inherited-row snapshots during the run, revoke issued sessions and close
Spring before deleting the owned databases/roles by their recorded OIDs. Do not
claim row restoration when the actual cleanup removes the whole disposable store.
A selected verify proves this focal slice plus packaging, not unrestricted
mvn verify, the broad host release gate, or a published/deployed release. The
financial authority logs its governance actors in through /auth/login. Case
principals receive persistent sessions through EnterpriseSessionLifecycle.issue;
the pilots verify HTTP SESSION admission/revocation, not password/identity-provider
login for those case principals. Config governance uses a fixed host tenant and
ordinary API/Config runtimes.
That is not multitenant Config rollout, browser login, CSRF or general departmental
authorization proof. Preserve the explicit policy/mock boundaries in the current
fixture and record skipped/aborted cases separately. Prior private-candidate
passes remain tied to their source and dependency hashes; an integrated PR or
unchanged GAV does not turn them into public-artifact evidence.
Boundaries
- Quickstart owns host wiring, data, security, paths, and operational evidence.
- Metadata starter owns schemas, discovery, capabilities, option contracts, and
resource semantics. Angular owns runtime materialization.
- Do not add aliases, schema patches, duplicate Cockpit assets, or host-local
decision logic to make a smoke pass.
Close with resource key, operations proved, fixtures, commands, sanitized HTTP
outcomes, cleanup state, and unresolved owner follow-up. A pilot is useful only
when another host can reproduce the platform behavior from its evidence.
1---2name: praxis-java-quickstart-proof3description: "Use when creating, extending, or auditing a Praxis API Quickstart operational proof for a Java resource: real HTTP schemas, OpenAPI, filters, option sources, actions, surfaces, capabilities, errors, stats/export, test data, write readback/cleanup, Cockpit verification, and downstream starter/runtime evidence."4metadata:5 source: https://skillmd.com/skills/codexrodrigues/praxis-java-quickstart-proof6---78# Praxis Java Quickstart Proof910Treat Quickstart as an operational proof host, never the owner of starter semantics.11Choose one representative resource and prove a canonical path by HTTP with fixtures12that demonstrate both success and an important negative condition.1314## Build The Proof Slice1516Inspect `ApiPaths`, controller, service, DTO/filter/action, mapper, option source,17test fixtures, security/origin setup, and existing pilot integration tests. Reuse18an existing pilot when it proves the same capability; do not copy a domain only19to make a new example. Fix a starter gap in the starter, then add the smallest20downstream proof here.2122## Required Evidence23241. Prove resource identity in OpenAPI and `/schemas/filtered`, including stable25 path/resource key, request/response operation schemas, `x-ui`, ETag and hash.262. Exercise each published operation in scope: filter/read, lookup reload,27 action/surface/capabilities, stats/export, or write. Verify `_links` and28 collection/item discovery agree.293. Include a negative case: invalid payload, missing resource, denied state,30 invalid filter/option request, conflict, or policy limit. Prove no mutation31 follows a rejected write.324. For database-backed proof, use explicitly assigned isolated Neon branches;33 unit tests without a database may run locally. For writes, retain controlled34 fixtures, read-after-write, side-effect evidence and cleanup. Do not substitute35 H2, embedded/local PostgreSQL or an unassigned parent/production branch.365. Run the relevant `QuickstartMetadataMigrationIntegrationTest`,37 `EventosFolhaPilotIntegrationTest`, focused pilot test, or Cockpit verifier.38 Review direct Angular runtime proof when the published contract changes.3940Read [proof-slice-matrix.md](references/proof-slice-matrix.md) when selecting41the smallest representative resource and required evidence.4243Before provisioning, distinguish no-database checks, still-valid evidence,44reattestation of the current exclusive campaign and a necessary new physical45branch. A new source/phase/retry/release does not by itself require a new branch.46Campaign means one bounded active test/suite execution: create just in time and47physically delete immediately after its last use, including failure/cancellation,48not per test method and not retained across idle sessions or pending PRs. Keep49sanitized receipts, not old branches for later restoration. The provisioner owns50control-plane closure, including failure before runner materialization; fixture51cleanup and `always()` do not certify branch deletion. Native TTL is only a52cleanup-failure backstop; uncertain deletion needs reconciliation and no false53success. Respect tool confirmation and scope; never delete parent/production.54Follow the workspace AGENTS branch lifecycle: bind project/branch IDs, exclusive55owner, purpose, baseline and fixed custody deadline; each attempt still needs its56own current source/dependencies and gate-valid assignment. Sequential reuse needs57closed prior connections, reconciled effects, proven fixture cleanup and required58initial state, fresh control-plane/PG/TLS/privilege observation. Never share across59concurrent workers or replace a required virgin clone with logical cleanup.60Set and read back native `expires_at` before SQL/host startup, normally within6148 hours for the campaign including transitions/cleanup; execution leases must fit62that fixed authorized custody. No rolling extension per retry. A local assignment63expiry does not delete the Neon branch. Use a designated durable baseline and an64independent leaf per concurrent campaign: Neon rejects TTL on parents,65default/protected branches and children of expiring parents. Do not remove TTL or66reuse a shared database to bypass this. After campaign completion, definitive67failure or cancellation, close owned hosts/connections and perform authorized68physical branch cleanup with readback; uncertain outcomes block serial reuse;69keep native TTL as the failure backstop. Preserve referenced fixtures, backups70and other workers' reservations; exceptions need IDs, current need, owner and71review deadline. Historical pins or a prior hold do not establish perpetual need.72See the official73[expiration restrictions](https://neon.com/docs/guides/branch-expiration).7475## Focal Proof And The Integral Neon Gate7677A focused pilot proves its selected behavior. It does not accept the host's78integral release gate, even when its Maven goal is `verify`. For starter adoption,79bootstrap or packaging changes that require the wider gate, follow the existing80[`praxis-api-quickstart-operational-proof` procedure](../praxis-api-quickstart-operational-proof/references/integral-neon-gate.md).81Verify the final private source and generated sanitized tree in sequence against82the same public coordinates, with separately attributable reports and cleanup.8384Retain every required test and its assertions. Inventory optional cases by exact85class/method, existing opt-in condition and reason; report skipped/aborted cases86by name rather than accepting a total alone. Optional lanes outside the selected87gate remain explicitly unproved. Missing assignment, new exclusions, disabled88tests or an empty selection cannot produce a passing database proof. Keep raw89logs, credentials and failure reports private until their export is reviewed;90publish only the closed, sanitized evidence projection.9192## Published SDK Adoption On Neon9394Inspect the Quickstart POM, `src/test/java/com/example/praxis/apiquickstart/config/MetadataAdoptionNeonFixture.java`,95its unit tests, `src/test/resources/metadata-adoption/neon-fixture.sql`, and the three96Metadata downstream pilots before selecting this gate. This route proves host97consumption of published SDKs; it does not publish an SDK or release the host.98991. Verify the public POM/JAR bytes first, then adopt the published coordinates in100 the host POM. Resolve through `.mvn/ql07-central-only-settings.xml` and a fresh101 isolated Maven repository. Do not use a local SDK install, candidate GAV or102 `praxis.core.version`/`praxis.config.version` override as public-adoption proof.1032. Inspect the current `MetadataAdoptionNeonFixture` and104 `config/neon/AssignedNeonStores`: the reviewed PR #482 fixture uses the shared105 Quickstart assignment, not the historical three-file adoption lease. Follow106 [the integral gate's assignment procedure](../praxis-api-quickstart-operational-proof/references/integral-neon-gate.md)107 to bind `PRAXIS_QUICKSTART_NEON_ASSIGNMENT_FILE`, its SHA-256, run ID,108 expected repository and source SHA. Confirm the target checkout contains this109 fixture before executing; do not apply candidate guidance to an older release.110 Keep credential files private and outside source/artifacts. Never copy111 passwords/DSNs into guidance, manifests, reports or command arguments, or reuse112 historical endpoint/expiry values. Serialize classes sharing the SDK roles.1133. Confirm endpoint/TLS/PostgreSQL identity and actual role privileges before114 mutation. Owner may prepare and remove only assigned fixture databases/roles. The application115 uses ordinary API and Config runtimes: neither may be superuser, bypass RLS,116 create roles/databases, or be a member of `neondb_owner`/`neon_superuser` and117 assume those roles. Direct privilege flags alone do not prove this separation.1184. Enable the official external-test opt-in, retain all selected cases and use119 the host's published POM without overrides. From the Quickstart checkout, with120 the assignment inputs exported and an absolute fresh repository path in121 `PRAXIS_ADOPTION_MAVEN_REPO`:122123```bash124: "${PRAXIS_ADOPTION_MAVEN_REPO:?Set an absolute fresh isolated Maven repository}"125PRAXIS_EXTERNAL_SMOKE_TESTS=true mvn -B -ntp \126 -s .mvn/ql07-central-only-settings.xml \127 "-Dmaven.repo.local=$PRAXIS_ADOPTION_MAVEN_REPO" \128 -Dtest=OpenApiGroupResolutionIsolatedIntegrationTest,QuickstartMetadataMigrationIntegrationTest,EventosFolhaPilotIntegrationTest \129 -Dsurefire.failIfNoSpecifiedTests=true verify130```131132Require the reviewed selection's full case count and zero failures, errors and133skips (currently 43 cases across these three classes). Missing inputs must fail134closed; an opt-in-disabled/skipped run is not a proof. Bind raw reports, source135and SQL hashes, resolved public dependency bytes and packaged dependencies to136this exact run and child assignment.137138If a failed assertion is corrected without changing production source, dependencies,139shared fixtures or the passing classes, rerun the affected class with separate140reports after verified cleanup. Reuse the cache only when its exclusively public141origin remains proven. Preserve the negative run and compare source/dependency142hashes before retaining earlier passes. Require the complete case matrix to pass;143label combined evidence explicitly rather than claiming a single green 43-case144run. Changes to shared fixtures or runtime behavior invalidate the affected prior145passes and require those cases to run again.146147Use the official bootstrap and migrations on the assigned databases. The148financial fixture must activate approved governance through the real Config149publication path and write payroll/events through admitted HTTP actions; SQL150inserts into those governed aggregates cannot replace that authority. Scope151nonfinancial seed and assertions to unique case IDs, including unique text keys.152Preserve inherited-row snapshots during the run, revoke issued sessions and close153Spring before deleting the owned databases/roles by their recorded OIDs. Do not154claim row restoration when the actual cleanup removes the whole disposable store.155156A selected `verify` proves this focal slice plus packaging, not unrestricted157`mvn verify`, the broad host release gate, or a published/deployed release. The158financial authority logs its governance actors in through `/auth/login`. Case159principals receive persistent sessions through `EnterpriseSessionLifecycle.issue`;160the pilots verify HTTP SESSION admission/revocation, not password/identity-provider161login for those case principals. Config governance uses a fixed host tenant and162ordinary API/Config runtimes.163That is not multitenant Config rollout, browser login, CSRF or general departmental164authorization proof. Preserve the explicit policy/mock boundaries in the current165fixture and record skipped/aborted cases separately. Prior private-candidate166passes remain tied to their source and dependency hashes; an integrated PR or167unchanged GAV does not turn them into public-artifact evidence.168169## Boundaries170171- Quickstart owns host wiring, data, security, paths, and operational evidence.172- Metadata starter owns schemas, discovery, capabilities, option contracts, and173 resource semantics. Angular owns runtime materialization.174- Do not add aliases, schema patches, duplicate Cockpit assets, or host-local175 decision logic to make a smoke pass.176177Close with resource key, operations proved, fixtures, commands, sanitized HTTP178outcomes, cleanup state, and unresolved owner follow-up. A pilot is useful only179when another host can reproduce the platform behavior from its evidence.