ctxora 6.2.2 → 6.4.0

package/src/harness_context/skills/ecc/ito-inference/LICENSE.ecc

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Affaan Mustafa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/src/harness_context/skills/ecc/ito-inference/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: ito-inference
+description: Inspect the availability of model serving on a completed Itô compute booking and, when the canonical backend becomes available, hand off an explicitly confirmed serving manifest. Use after ito-compute has booked GPU nodes and the user asks for an OpenAI-compatible endpoint, ito-serve, hosted Kimi, or self-hosted open-weights inference. ECC implements no serving stack of its own.
+metadata:
+  origin: ECC
+  status: scaffold
+  aliases: ito-serve, hosted-open-weights
+---
+
+# Itô Inference
+
+`ito-inference` is the sole canonical ECC skill for inference serving on Itô
+compute. Requests naming `ito-serve` route here; do not create or install a
+second `ito-serve` skill. ECC never SSHes to nodes, downloads weights, launches
+an engine, or exposes an endpoint; it never books, reserves, or spends.
+
+## Current production boundary
+
+Managed serving is unavailable today. The ECC bridge exposes only `login`,
+`auth`, `find`, `status`, and explicitly gated `evals`. It has no `serve` verb.
+The canonical runtime documents `inference` only as an unsupported compatibility
+probe; ECC does not invoke or depend on it. The MCP surface exposes only auth,
+find, and status. The locally enforceable guarantee is that ECC rejects `serve`
+before resolving or spawning the credential-bearing canonical client.
+
+Therefore stop before authentication or any command invocation. Report the
+missing capability and return to the originating agent. Never substitute a
+local runner, SSH helper, browser workflow, purchase endpoint, or any untracked
+local `ito-serve` draft.
+
+## Required entitlement
+
+When serving is implemented, its first gate is a server-verified completed
+booking. Harness memory, an RFQ, a quote, node IPs, or SSH access are not proof
+of entitlement. The backend must return fresh serving eligibility bound to the
+authenticated account, booking, GPU topology, region, fabric, term, and model
+policy. Expired, revoked, mismatched, incomplete, or already-released bookings
+fail closed before confirmation.
+
+## Future CLI and API contract
+
+The intended command name is `serve`; `inference` may remain only as an
+explicitly deprecated compatibility alias after the production contract lands.
+The future handoff must be equivalent to:
+
+```sh
+ecc ito serve \
+  --booking <server-verified-booking-id> \
+  --manifest <absolute-reviewed-json-file> \
+  --confirmation-ref <opaque-non-authorizing-reference> \
+  --idempotency-key <stable-retry-key> \
+  --json
+```
+
+The reviewed manifest must identify the model revision, engine and version,
+quantization, tensor/pipeline topology, endpoint exposure policy, artifact
+checksums, storage ceiling, runtime limits, optional TTFT/TPOT objectives, and
+maximum incremental cost. No raw API key, SSH key, node password, or bearer
+token belongs in arguments, manifests, logs, MCP results, or chat.
+
+The client must canonicalize the manifest path, reject symlinks, open a regular
+file without following links, require appropriate ownership and restrictive
+permissions, enforce a bounded size, and hash bytes from the opened descriptor.
+That digest must exactly equal the digest bound into confirmation before any
+workload mutation. A path swap, digest mismatch, oversized file, or mutable
+unsafe file fails closed.
+
+The canonical API—not ECC—must own workload creation and return structured JSON
+with `ok`, `live_api_contacted`, `notice`, and either `data` or `error`. Serving
+data must include stable booking, workload, manifest, and idempotency IDs plus a
+state enum; it must not claim an endpoint is live until health and model checks
+pass. Errors must include a stable code and safe message without secrets.
+
+## Confirmation and execution gates
+
+Before workload creation, require all of the following:
+
+1. Fresh entitlement and serving eligibility from the canonical backend.
+2. A reviewable immutable manifest and deterministic digest.
+3. A separate single-use confirmation bound to account, action, manifest, and
+   cost, with a short expiry and replay protection. CLI arguments carry only an
+   opaque, non-authorizing confirmation reference; the server resolves and
+   consumes the bearer capability out of band.
+4. A caller-supplied idempotency key reserved atomically with the workload.
+5. Server-side fabric, capacity, model-policy, storage, and cost validation.
+
+Authentication is identity, not workload authority. A login, API key, quote,
+or completed booking never substitutes for the serving confirmation. Inspection
+and plan generation must not create a workload. Cancel and cleanup are separate
+mutations with their own scoped confirmation and idempotency boundaries.
+
+## Lifecycle and recovery
+
+The production surface is incomplete until the same canonical client exposes
+tenant-scoped status, logs, metrics, cancel, and cleanup operations. Every
+operation needs bounded connect and overall timeouts, revocation-aware errors,
+and structured output. After an ambiguous transport failure, query status by
+the idempotency key before retrying; never create a second workload merely
+because the first response was lost. A revoked credential stops polling and
+returns control to the originating agent without starting login automatically.
+
+Only report `ready` after endpoint health, model identity, and canary inference
+all pass. Report intermediate and terminal failure states honestly. Cleanup must
+be observable and must not release or modify the underlying booking unless that
+separate economic action was explicitly authorized.
+
+## Proposed backend stages
+
+These stages describe the future backend, not code that exists in ECC:
+
+1. Verify entitlement, topology, fabric, and cost gates.
+2. Fetch checksum-pinned weights into backend-managed storage.
+3. Emit and validate a reviewable topology/engine plan.
+4. Launch through the provider control plane, never direct root SSH from ECC.
+5. Warm up, test health and model identity, run an SLO canary, then register the
+   endpoint and redacted configuration.
+
+Until every gate and lifecycle operation above exists in the canonical runtime,
+this skill remains a fail-closed availability check and documentation handoff.

package/src/harness_context/skills/ecc/ito-training/LICENSE.ecc

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Affaan Mustafa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/src/harness_context/skills/ecc/ito-training/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: ito-training
+description: Inspect the availability of ML training on a completed Itô compute booking and, when the canonical backend becomes available, hand off an explicitly confirmed training manifest. Use after ito-compute has booked GPU nodes and the user wants pre-training, fine-tuning, or RL on that metal. ECC implements no training stack of its own.
+metadata:
+  origin: ECC
+  status: scaffold
+---
+
+# Itô Training
+
+`ito-training` is the canonical ECC skill for training on Itô compute. ECC
+never runs a trainer, scheduler, or data pipeline of its own; it never books,
+reserves, or spends. This skill chains off a **completed booking** from
+`ito-compute`.
+
+## Current production boundary
+
+Managed training is unavailable today. The ECC bridge exposes only `login`,
+`logout`, `auth`, `find`, `status`, and explicitly gated `evals`. It has no
+`train` verb, and the canonical CLI's `run` verb and desk `training-run`
+backend remain scaffolds. The locally enforceable guarantee is that ECC rejects
+`train` before resolving or spawning the credential-bearing canonical client.
+
+Therefore stop before authentication or any command invocation. Report the
+missing capability and return to the originating agent. Never substitute a
+local trainer, SSH helper, browser workflow, or purchase endpoint.
+
+## Required entitlement
+
+When training is implemented, its first gate is a server-verified completed
+booking. Harness memory, an RFQ, a quote, node IPs, or SSH access are not proof
+of entitlement. The backend must return fresh training eligibility bound to the
+authenticated account, booking, GPU topology, region, fabric, and term.
+Expired, revoked, mismatched, incomplete, or already-released bookings fail
+closed before confirmation.
+
+## Future CLI and API contract
+
+The intended command name is `train`. The future handoff must be equivalent to:
+
+```sh
+ecc ito train \
+  --booking <server-verified-booking-id> \
+  --manifest <absolute-reviewed-json-file> \
+  --confirmation-ref <opaque-non-authorizing-reference> \
+  --idempotency-key <stable-retry-key> \
+  --json
+```
+
+The reviewed manifest must identify the model size and revision, data
+references with decontamination provenance, training target, post-training
+recipe, budget ceiling in USD, checkpoint policy, and maximum incremental
+cost. No raw API key, SSH key, node password, bearer token, or dataset
+credential belongs in arguments, manifests, logs, MCP results, or chat.
+
+The client must canonicalize the manifest path, reject symlinks, open a regular
+file without following links, require appropriate ownership and restrictive
+permissions, enforce a bounded size, and hash bytes from the opened descriptor.
+That digest must exactly equal the digest bound into confirmation before any
+workload mutation. A path swap, digest mismatch, oversized file, or mutable
+unsafe file fails closed.
+
+The canonical API—not ECC—must own workload creation and return structured JSON
+with `ok`, `live_api_contacted`, `notice`, and either `data` or `error`.
+Training data must include stable booking, run, manifest, and idempotency IDs
+plus a state enum. Errors must include a stable code and safe message without
+secrets.
+
+## Confirmation and execution gates
+
+Before workload creation, require all of the following:
+
+1. Fresh entitlement and training eligibility from the canonical backend.
+2. A reviewable immutable manifest and deterministic digest.
+3. A separate single-use confirmation bound to account, action, manifest, and
+   cost, with a short expiry and replay protection. CLI arguments carry only an
+   opaque, non-authorizing confirmation reference; the server resolves and
+   consumes the bearer capability out of band.
+4. A caller-supplied idempotency key reserved atomically with the run.
+5. Server-side fabric, capacity, data-policy, checkpoint-storage, and cost
+   validation, including the manifest's budget ceiling.
+
+Authentication is identity, not workload authority. A login, API key, quote,
+or completed booking never substitutes for the training confirmation.
+Inspection and plan generation must not create a workload. Cancel and cleanup
+are separate mutations with their own scoped confirmation and idempotency
+boundaries.
+
+## Lifecycle and recovery
+
+The production surface is incomplete until the same canonical client exposes
+tenant-scoped status, logs, metrics, checkpoint listing, cancel, and cleanup.
+Every operation needs bounded connect and overall timeouts, revocation-aware
+errors, and structured output. After an ambiguous transport failure, query
+status by the idempotency key before retrying; never create a second run merely
+because the first response was lost. A revoked credential stops polling and
+returns control to the originating agent without starting login automatically.
+
+Report stage gates honestly; never override a failed eval gate. Cleanup must be
+observable and must not release or modify the underlying booking unless that
+separate economic action was explicitly authorized.
+
+## Proposed backend stages
+
+These stages describe the future backend (Layer 0.3), not code that exists in
+ECC:
+
+1. Data prep — manifest, dedup, decontamination against the eval suite;
+   150M-ladder decision job as the cheap pre-check for custom data.
+2. Parallelism and precision — selected from model size, node count, fabric;
+   wasteful combinations refused.
+3. Checkpointing and fault tolerance — async DCP, torchft; detect < 10 min,
+   resume < 15 min. Loss-spike restart is a proposed, human-gated action.
+4. Curriculum and eval gates — staged pretrain / mid-train / long-context /
+   post-training, each with a fixed eval battery; a failed gate stops the run.
+5. Post-training — SFT → DPO → RLVR (GRPO with DAPO stability fixes),
+   trainer/rollout separation with bounded staleness.
+
+The backend emits desk telemetry (goodput, interruption rate, checkpoint
+bandwidth) so the desk prices training blocks honestly.
+
+Until every gate and lifecycle operation above exists in the canonical runtime,
+this skill remains a fail-closed availability check and documentation handoff.

package/src/harness_context/skills/ecc/java-coding-standards/LICENSE.ecc

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Affaan Mustafa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/src/harness_context/skills/ecc/java-coding-standards/SKILL.md

@@ -0,0 +1,384 @@
+---
+name: java-coding-standards
+description: "Java coding standards for Spring Boot and Quarkus services: naming, immutability, Optional usage, streams, exceptions, generics, CDI, reactive patterns, and project layout. Automatically applies framework-specific conventions. Use when writing or reviewing Java in a Spring Boot or Quarkus service."
+metadata:
+  origin: ECC
+---
+
+# Java Coding Standards
+
+Standards for readable, maintainable Java (17+) code in Spring Boot and Quarkus services.
+
+## When to Use
+
+- Writing or reviewing Java code in Spring Boot or Quarkus projects
+- Enforcing naming, immutability, or exception handling conventions
+- Working with records, sealed classes, or pattern matching (Java 17+)
+- Reviewing use of Optional, streams, or generics
+- Structuring packages and project layout
+- **[QUARKUS]**: Working with CDI scopes, Panache entities, or reactive pipelines
+
+## How It Works
+
+### Framework Detection
+
+Before applying standards, determine the framework from the build file:
+
+- Build file contains `quarkus` → apply **[QUARKUS]** conventions
+- Build file contains `spring-boot` → apply **[SPRING]** conventions
+- Neither detected → apply shared conventions only
+
+## Core Principles
+
+- Prefer clarity over cleverness
+- Immutable by default; minimize shared mutable state
+- Fail fast with meaningful exceptions
+- Consistent naming and package structure
+- **[QUARKUS]**: Favor build-time over runtime processing; avoid runtime reflection where possible
+
+## Examples
+
+The sections below show concrete Spring Boot, Quarkus, and shared Java examples
+for naming, immutability, dependency injection, reactive code, exceptions,
+project layout, logging, configuration, and tests.
+
+## Naming
+
+```java
+// PASS: Classes/Records: PascalCase
+public class MarketService {}
+public record Money(BigDecimal amount, Currency currency) {}
+
+// PASS: Methods/fields: camelCase
+private final MarketRepository marketRepository;
+public Market findBySlug(String slug) {}
+
+// PASS: Constants: UPPER_SNAKE_CASE
+private static final int MAX_PAGE_SIZE = 100;
+
+// PASS: [QUARKUS] JAX-RS resources named as *Resource, not *Controller
+public class MarketResource {}
+
+// PASS: [SPRING] REST controllers named as *Controller
+public class MarketController {}
+```
+
+## Immutability
+
+```java
+// PASS: Favor records and final fields
+public record MarketDto(Long id, String name, MarketStatus status) {}
+
+public class Market {
+  private final Long id;
+  private final String name;
+  // getters only, no setters
+}
+
+// PASS: [QUARKUS] Panache active-record entities use public fields (Quarkus convention)
+@Entity
+public class Market extends PanacheEntity {
+  public String name;
+  public MarketStatus status;
+  // Panache generates accessors at build time; public fields are idiomatic here
+}
+
+// PASS: [QUARKUS] Panache MongoDB entities
+@MongoEntity(collection = "markets")
+public class Market extends PanacheMongoEntity {
+  public String name;
+  public MarketStatus status;
+}
+```
+
+## Optional Usage
+
+```java
+// PASS: Return Optional from find* methods
+// [SPRING]
+Optional<Market> market = marketRepository.findBySlug(slug);
+
+// [QUARKUS] Panache
+Optional<Market> market = Market.find("slug", slug).firstResultOptional();
+
+// PASS: Map/flatMap instead of get()
+return market
+    .map(MarketResponse::from)
+    .orElseThrow(() -> new EntityNotFoundException("Market not found"));
+```
+
+## Streams Best Practices
+
+```java
+// PASS: Use streams for transformations, keep pipelines short
+List<String> names = markets.stream()
+    .map(Market::name)
+    .filter(Objects::nonNull)
+    .toList();
+
+// FAIL: Avoid complex nested streams; prefer loops for clarity
+```
+
+## Dependency Injection
+
+```java
+// PASS: [SPRING] Constructor injection (preferred over @Autowired on fields)
+@Service
+public class MarketService {
+  private final MarketRepository marketRepository;
+
+  public MarketService(MarketRepository marketRepository) {
+    this.marketRepository = marketRepository;
+  }
+}
+
+// PASS: [QUARKUS] Constructor injection
+@ApplicationScoped
+public class MarketService {
+  private final MarketRepository marketRepository;
+
+  @Inject
+  public MarketService(MarketRepository marketRepository) {
+    this.marketRepository = marketRepository;
+  }
+}
+
+// PASS: [QUARKUS] Package-private field injection (acceptable in Quarkus — avoids proxy issues)
+@ApplicationScoped
+public class MarketService {
+  @Inject
+  MarketRepository marketRepository;
+}
+
+// FAIL: [SPRING] Field injection with @Autowired
+@Autowired
+private MarketRepository marketRepository; // use constructor injection
+
+// FAIL: [QUARKUS] @Singleton when interception or lazy init is needed
+@Singleton // non-proxyable — use @ApplicationScoped instead
+public class MarketService {}
+```
+
+## Reactive Patterns [QUARKUS]
+
+```java
+// PASS: Return Uni/Multi from reactive endpoints
+@GET
+@Path("/{slug}")
+public Uni<Market> findBySlug(@PathParam("slug") String slug) {
+  return Market.find("slug", slug)
+      .<Market>firstResult()
+      .onItem().ifNull().failWith(() -> new MarketNotFoundException(slug));
+}
+
+// PASS: Non-blocking pipeline composition
+public Uni<OrderConfirmation> placeOrder(OrderRequest req) {
+  return validateOrder(req)
+      .chain(valid -> persistOrder(valid))
+      .chain(order -> notifyFulfillment(order));
+}
+
+// FAIL: Blocking call inside a Uni/Multi pipeline
+public Uni<Market> find(String slug) {
+  Market m = Market.find("slug", slug).firstResult(); // BLOCKING — breaks event loop
+  return Uni.createFrom().item(m);
+}
+
+// FAIL: Subscribing more than once to a shared Uni
+Uni<Market> shared = fetchMarket(slug);
+shared.subscribe().with(m -> log(m));
+shared.subscribe().with(m -> cache(m)); // double subscribe — use Uni.memoize()
+```
+
+## Exceptions
+
+- Use unchecked exceptions for domain errors; wrap technical exceptions with context
+- Create domain-specific exceptions (e.g., `MarketNotFoundException`)
+- Avoid broad `catch (Exception ex)` unless rethrowing/logging centrally
+
+```java
+throw new MarketNotFoundException(slug);
+```
+
+### Centralised Exception Handling
+
+```java
+// [SPRING]
+@RestControllerAdvice
+public class GlobalExceptionHandler {
+  @ExceptionHandler(MarketNotFoundException.class)
+  public ResponseEntity<ErrorResponse> handle(MarketNotFoundException ex) {
+    return ResponseEntity.status(404).body(ErrorResponse.from(ex));
+  }
+}
+
+// [QUARKUS] Option A: ExceptionMapper
+@Provider
+public class MarketNotFoundMapper implements ExceptionMapper<MarketNotFoundException> {
+  @Override
+  public Response toResponse(MarketNotFoundException ex) {
+    return Response.status(404).entity(ErrorResponse.from(ex)).build();
+  }
+}
+
+// [QUARKUS] Option B: @ServerExceptionMapper (RESTEasy Reactive)
+@ServerExceptionMapper
+public RestResponse<ErrorResponse> handle(MarketNotFoundException ex) {
+  return RestResponse.status(Status.NOT_FOUND, ErrorResponse.from(ex));
+}
+```
+
+## Generics and Type Safety
+
+- Avoid raw types; declare generic parameters
+- Prefer bounded generics for reusable utilities
+
+```java
+public <T extends Identifiable> Map<Long, T> indexById(Collection<T> items) { ... }
+```
+
+## Project Structure
+
+### [SPRING] Maven/Gradle
+
+```
+src/main/java/com/example/app/
+  config/
+  controller/
+  service/
+  repository/
+  domain/
+  dto/
+  util/
+src/main/resources/
+  application.yml
+src/test/java/... (mirrors main)
+```
+
+### [QUARKUS] Maven/Gradle
+
+```
+src/main/java/com/example/app/
+  config/              # @ConfigMapping, @ConfigProperty beans, Producers
+  resource/            # JAX-RS resources (not "controller")
+  service/
+  repository/          # PanacheRepository implementations (if not using active record)
+  domain/              # JPA/Panache entities, MongoDB entities
+  dto/
+  util/
+  mapper/              # MapStruct mappers (if used)
+src/main/resources/
+  application.properties   # Quarkus convention (YAML supported with quarkus-config-yaml)
+  import.sql               # Hibernate auto-import for dev/test
+src/test/java/... (mirrors main)
+```
+
+## Formatting and Style
+
+- Use 2 or 4 spaces consistently (project standard)
+- One public top-level type per file
+- Keep methods short and focused; extract helpers
+- Order members: constants, fields, constructors, public methods, protected, private
+
+## Code Smells to Avoid
+
+- Long parameter lists → use DTO/builders
+- Deep nesting → early returns
+- Magic numbers → named constants
+- Static mutable state → prefer dependency injection
+- Silent catch blocks → log and act or rethrow
+- **[QUARKUS]**: `@Singleton` where `@ApplicationScoped` is intended — breaks proxying and interception
+- **[QUARKUS]**: Mixing `quarkus-resteasy-reactive` and `quarkus-resteasy` (classic) — pick one stack
+- **[QUARKUS]**: Panache active-record + repository pattern in the same bounded context — pick one
+
+## Logging
+
+```java
+// [SPRING] SLF4J
+private static final Logger log = LoggerFactory.getLogger(MarketService.class);
+log.info("fetch_market slug={}", slug);
+log.error("failed_fetch_market slug={}", slug, ex);
+
+// [QUARKUS] JBoss Logging (default, zero-cost at build time)
+private static final Logger log = Logger.getLogger(MarketService.class);
+log.infof("fetch_market slug=%s", slug);
+log.errorf(ex, "failed_fetch_market slug=%s", slug);
+
+// [QUARKUS] Alternative: simplified logging with @Inject
+@Inject
+Logger log; // CDI-injected, scoped to declaring class
+```
+
+## Null Handling
+
+- Accept `@Nullable` only when unavoidable; otherwise use `@NonNull`
+- Use Bean Validation (`@NotNull`, `@NotBlank`) on inputs
+- **[QUARKUS]**: Apply `@Valid` on `@BeanParam`, `@RestForm`, and request body parameters
+
+## Configuration
+
+```java
+// [SPRING] @ConfigurationProperties
+@ConfigurationProperties(prefix = "market")
+public record MarketProperties(int maxPageSize, Duration cacheTtl) {}
+
+// [QUARKUS] @ConfigMapping (type-safe, build-time validated)
+@ConfigMapping(prefix = "market")
+public interface MarketConfig {
+  int maxPageSize();
+  Duration cacheTtl();
+}
+
+// [QUARKUS] Simple values with @ConfigProperty
+@ConfigProperty(name = "market.max-page-size", defaultValue = "100")
+int maxPageSize;
+```
+
+## Testing Expectations
+
+### Shared
+- JUnit 5 + AssertJ for fluent assertions
+- Mockito for mocking; avoid partial mocks where possible
+- Favor deterministic tests; no hidden sleeps
+
+### [SPRING]
+- `@WebMvcTest` for controller slices, `@DataJpaTest` for repository slices
+- `@SpringBootTest` reserved for full integration tests
+- `@MockBean` for replacing beans in Spring context
+
+### [QUARKUS]
+- Plain JUnit 5 + Mockito for unit tests (no `@QuarkusTest`)
+- `@QuarkusTest` reserved for CDI integration tests
+- `@InjectMock` for replacing CDI beans in integration tests
+- Dev Services for database/Kafka/Redis — avoid manual Testcontainers setup when Dev Services suffice
+- `@QuarkusTestResource` for custom external service lifecycle
+
+```java
+// [SPRING] Controller test
+@WebMvcTest(MarketController.class)
+class MarketControllerTest {
+  @Autowired MockMvc mockMvc;
+  @MockBean MarketService marketService;
+}
+
+// [QUARKUS] Integration test
+@QuarkusTest
+class MarketResourceTest {
+  @InjectMock
+  MarketService marketService;
+
+  @Test
+  void should_return_404_when_market_not_found() {
+    given().when().get("/markets/unknown").then().statusCode(404);
+  }
+}
+
+// [QUARKUS] Unit test (no CDI, no @QuarkusTest)
+@ExtendWith(MockitoExtension.class)
+class MarketServiceTest {
+  @Mock MarketRepository marketRepository;
+  @InjectMocks MarketService marketService;
+}
+```
+
+**Remember**: Keep code intentional, typed, and observable. Optimize for maintainability over micro-optimizations unless proven necessary.