Axiomatic Reasoning for LLMs

Implementation Plan on Java

1. Target Architecture

This plan defines a Java implementation of Deep Coding based on three core layers:

• Structural Specification Layer
  Machine-readable definitions (OpenAPI, JSON Schema, custom annotations) that serve as the single source of truth.

• Skeleton Layer
  Immutable interfaces, abstract classes, and module declarations generated from specifications. Human modification is prohibited.

• Tissue Layer
  Concrete implementations (controllers, services, repositories). Fully generated where possible; partially generated or manually written where domain complexity requires.

2. Phase 1: Structural Specification

2.1. API Contract

• Use OpenAPI 3.0+ YAML to define endpoints, request/response schemas, and operation IDs.
• Place under src/main/resources/openapi/.

2.2. Data Structure Contract

• Use JSON Schema for complex data models not fully captured in OpenAPI.
• Use jsonschema2pojo to generate POJOs with Jackson annotations.

2.3. Domain Contract

• Use custom annotations + annotation processors for state transitions, business rules, and cross-cutting constraints.
• Example: @StateTransition(from = "DRAFT", to = "PUBLISHED") generates compile-time validation.

2.4. Module Contract

• Use Java Platform Module System (JPMS) with module-info.java to declare exports, dependencies, and service bindings.
• Treat module-info.java as a generated artifact derived from the structural specification.

3. Phase 2: Generative Conformance

3.1. Build-Time Code Generation

• Integrate generators into Maven or Gradle lifecycle.

Generator	Input	Output	Plugin
OpenAPI Generator	OpenAPI YAML	API interfaces, DTOs	openapi-generator-maven-plugin
jsonschema2pojo	JSON Schema	POJOs	jsonschema2pojo-maven-plugin
Custom annotation processor	Java annotations	Validators, monitors	maven-compiler-plugin (built-in)

• Output all generated code to target/generated-sources/ and exclude from version control.

3.2. Incremental Generation

• Use Gradle’s task input/output tracking or Maven’s incremental build plugin to regenerate only modules affected by specification changes.

3.3. Generation Rules

• Skeleton: Generate only interfaces and abstract classes. Do not modify manually.
• Tissue (data): Fully generate DTOs and validators.
• Tissue (logic): Generate stub implementations when possible; manual implementation is permitted but must conform to skeleton interfaces.

4. Phase 3: Skeleton–Tissue Separation

4.1. Skeleton Layer Implementation

Pattern	Java Construct	Role
Template Method	abstract class with final template method	Immutable algorithm structure
Interface Contract	Generated API interfaces	Invariant operation signatures
Module Boundary	module-info.java	Physical encapsulation

4.2. Tissue Layer Implementation

• Generated Tissue
  DTOs, enums, validators, and state monitors are fully generated and never manually edited.

• Semi-Generated Tissue
  Controllers implement generated interfaces. Implementation can be AI-generated but must be verified against the specification.

• Manual Tissue
  Service classes contain domain logic. They must be written to depend only on skeleton interfaces and generated DTOs.

4.3. Dependency Direction Enforcement

Use ArchUnit to enforce:

• Controllers depend only on services and DTOs.
• Services depend only on repositories and DTOs.
• No circular dependencies between modules.

5. Phase 4: Validation Gates

5.1. Compile-Time Gates

Gate	Tool	Enforced Property
Module integrity	JPMS	No cyclic dependencies; exported packages only
Null safety	Checker Framework (NullnessChecker)	@NonNull/@Nullable contracts
Type state	Checker Framework (OptionalChecker)	Correct Optional usage
Custom constraints	Annotation processors	State transitions, business rules

Configure Checker Framework in Maven:

<plugin>
    <groupId>org.checkerframework</groupId>
    <artifactId>checkerframework-maven-plugin</artifactId>
    <configuration>
        <processors>
            <processor>org.checkerframework.checker.nullness.NullnessChecker</processor>
        </processors>
    </configuration>
</plugin>

5.2. Test-Time Gates

Use ArchUnit to enforce:

• Package structure: generated code resides only in *.generated.*.
• Naming conventions: implementation classes end with Impl.
• Dependency rules: no direct access from controllers to repositories.

Example ArchUnit test:

@Test
void generated_packages_are_not_manually_modified() {
    JavaClasses classes = new ClassFileImporter().importPackages("com.example");
    ArchRule rule = noClasses()
        .that().resideInAPackage("..generated..")
        .should().beAnnotatedWith(NotGenerated.class);
    rule.check(classes);
}

5.3. CI/CD Integration

• Fail the build if any validation gate fails.
• Require all gates to pass before merging to main branch.

6. Phase 5: Recursive Refinement

6.1. Specification Change Workflow

1. Modify structural specification (OpenAPI YAML, JSON Schema, annotations).
2. Rebuild — triggers code regeneration.
3. Compile — any conformance violation (e.g., missing method in implementation) becomes a compilation error.
4. Fix — update tissue implementations to match the regenerated skeleton.
5. Re-run validation gates — ensure all architectural rules still hold.

6.2. Handling Non-Generated Code

• When service logic is manually written, specification changes may require manual refactoring.
• Use OpenRewrite to automate common refactorings across the codebase.

6.3. Rollback

• Because the specification is version controlled, any phase can be reverted by reverting the specification file and rebuilding.

7. Technology Stack Summary

Layer	Recommended	Alternative
Framework	Quarkus (compile-time DI)	Spring Boot with AOT enabled
Build Tool	Gradle (incremental builds, task dependencies)	Maven with incremental build plugin
Specification	OpenAPI + JSON Schema + custom annotations	—
Code Generation	OpenAPI Generator + jsonschema2pojo + annotation processors	—
Static Analysis	Checker Framework + ArchUnit	Error Prone + SpotBugs
Module System	JPMS (Java 9+)	Package conventions (if JPMS not feasible)

8. Constraints and Limitations

Constraint	Mitigation
Reflection-heavy frameworks (Spring traditional)	Use constructor injection; limit Deep Coding scope to contract layer
Bytecode manipulation tools (Lombok)	Avoid; replace with explicit code or MapStruct (generated, visible sources)
Existing legacy codebases	Apply Deep Coding only to new modules; incrementally extract structural specifications from legacy code
Cross-team coordination	Enforce only interface-level contracts; allow internal implementation flexibility

9. Implementation Checklist

• Define OpenAPI YAML for all public APIs.
• Configure OpenAPI Generator in build with interfaceOnly=true.
• Define JSON Schema for complex data models.
• Configure jsonschema2pojo for POJO generation.
• Implement custom annotations and processors for domain constraints.
• Add JPMS module-info.java and configure exports.
• Configure Checker Framework for null safety.
• Write ArchUnit tests for architectural rules.
• Set up CI pipeline to fail on validation errors.
• Apply recursive refinement workflow to all specification changes.

This site is open source. Improve this page.