diff --git a/README.md b/README.md index 6173a8cd..2bc0035d 100644 --- a/README.md +++ b/README.md @@ -1,57 +1,74 @@ # TeaQL Java -Review the business operation, not pages of persistence plumbing. +An AI-native library and runtime for building reviewable business applications in Java. -TeaQL Java is a reusable, domain-independent runtime for model-aware applications. -A generated domain library gives your application language-native **Q** queries, -**E** expressions and governed graph mutations. The runtime executes them -through metadata, Context, Checker, Policy and provider boundaries. +TeaQL gives coding agents business-shaped APIs, model-aware guidance and +software checks. People review the business operation instead of reconstructing +pages of query-building, relationship-loading and persistence code. -The goal is to let people and coding agents express—and review—business intent -in a small amount of application code. +Automatic execution logs make those operations easier to debug and operate, +without adding logging statements to every business method. + +[Try with your coding agent](#try-it-with-your-coding-agent) · +[Run the local example](#run-the-local-example) · +[See automatic logs](#automatic-logs-without-handwritten-logging-code) [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/13612/badge)](https://www.bestpractices.dev/projects/13612) -## What you gain +## Why this is an AI native library -| Capability | Benefit to application developers | -| --- | --- | -| Composable Q API | Combine filters, projections and relation requests without duplicating relationship-loading code; review what is being requested. | -| Safe E API | Distinguish an unloaded field from a loaded NULL; do not mistake an incomplete result for a business fact. | -| Governed graph Save | Stage creates, updates and deletions, then validate and persist through one Save boundary rather than hand-written SQL loops. | -| Execution and audit evidence | Follow declared intent, SQL routes and mutation responsibility when debugging or explaining a change. | +AI-native does not mean the library was written by AI, or that every query +calls an LLM. It means the APIs, knowledge delivery and verification workflow +are designed for how coding agents work: limited context, incomplete knowledge +of a project and a tendency to guess unfamiliar operations. -## Try it with your coding agent +The semantic model describes your business objects, fields, relationships and +states. A generated domain library turns those words into language-native +**Q** queries, **E** expressions and mutation methods. This repository provides +the reusable, domain-independent **runtime** that executes them through +metadata, Context, Checker, Policy and database providers. -You can start with an agent you already use. Paste this prompt: +The application workspace keeps business code and concise project guidance +together. Progressive **Assist** supplies the exact API guidance needed for +the next operation, instead of asking the agent to explore the entire generated +library. Compilation, runtime checks and tests provide feedback beyond a prompt. -```text -Follow the current instructions at https://github.com/teaql/teaql-agent-kit. -Build a small school-management application in Java using SQLite. -Evaluate and repair the model, generate the library and workspace, then verify -Q, E, Checker and audited Save. Report commands, results and remaining frictions. -``` +## Less code for a reviewer to reconstruct -The [Agent Kit](https://github.com/teaql/teaql-agent-kit) guides modeling, -evaluation/repair, generation and application customization. It may install -toolchains and download dependencies; review installation permissions and the -final execution report. It is a workflow, not a guarantee of unattended correctness. +The benefit is visible in the application code: the query, data access path +and audited change stay together, while shared mechanics live in the library +and runtime. -## Run the local example +| Application code to review | Shared work handled by TeaQL | +| --- | --- | +| A composed Q request | SQL construction and selected relation loading | +| An E access path | Loaded-field checks and explicit NULL handling | +| A mutation with an audit reason | Change tracking, Checker and configured Policy execution | +| Business intent and audit reason | Automatic execution logs and trace context without per-operation logging code | -Java 17+ and Maven 3.8+. From a checkout of this repository: +Reviewers still decide whether the requested data, business rules and +authorization policy are correct. They have less application plumbing to +trace before making that decision; reuse does not make business logic correct +automatically. -```bash -bash examples/verify-runtime-examples.sh -``` +**Token savings have not yet been measured in a controlled comparison.** +We make no numerical token-saving claim. Loading guidance only when needed +is a context-management strategy; the smaller application review surface is +visible in the examples, not a measured percentage reduction in review time. -The [School example](examples/school-management/README.md) -exercises SQLite schema/bootstrap and generated application APIs against this -repository's local runtime. No external database server or generator is needed -to run the retained generated example. Use only the example's test database; -reset/repeated-run behavior is documented in its README. +## See a business operation execute + +The [Robot Task Board showcase](https://teaql.io/blog/robot-task-board-showcase/) +makes the idea concrete: move a task and follow the state change, generated +SQL, field-level audit and refreshed board. + +![TeaQL Robot Task Board](https://teaql.io/img/003-task-board.png) -## Query and read the result +Explore the [open-source demo](https://github.com/teaql/robot-task-board). +The showcase is a Rust application; the examples below use this repository's +own Java APIs. + +## Q API composes business queries These application-code excerpts assume the example's generated imports, trusted Context and an existing object identity. `Q` and `E` belong to the generated @@ -59,31 +76,45 @@ domain library, not a generic runtime object with arbitrary field strings. See the [application source](examples/school-management/src/main/java/com/example/schoolmanagementservice/SchoolLifecycleVerifier.java) for complete setup. ```java +var schoolTypeDetails = Q.schoolTypesWithMinimalFields().selectCode(); + School school = Q.schools() .withIdIs(schoolId) .selectPlatformWith(Q.platformsWithMinimalFields().selectName()) - .selectSchoolTypeWith(Q.schoolTypesWithMinimalFields().selectCode()) + .selectSchoolTypeWith(schoolTypeDetails) .comment("what: load the school and its reference data") .purpose("why: review a school before editing") .executeForOne(context); if (school == null) throw new IllegalStateException("School not found"); ``` -The selected relation request is another typed query: it can be composed and -reused independently. `comment` describes **what**; `purpose` describes **why**. -Both must be non-empty, even when logging is disabled. +The child request is a query in its own right. Give it a business name, +extract it into a helper and compose it into other requests like a Lego brick. +The reviewer can see which relationships are loaded without following a +separate set of SQL loops. `comment` describes **what**; `purpose` describes +**why**. Both must be non-empty, even when logging is disabled. + +## E API protects business reads ```java String name = E.school(school).getName().eval(); String typeCode = E.school(school).getSchoolType().eval().getCode(); ``` -E reads the loaded graph without implicitly querying the database. Unloaded -modeled fields remain guarded, rather than silently becoming NULL. The exact -error/result representation follows the language's API. A NULL fallback is -not permission to ignore an unloaded property. +E reads the loaded graph without implicitly querying the database. A loaded +NULL and a field that was **NotLoaded** are different facts. A business rule +must not conclude that a value is absent merely because the query never +requested it. + +The access path is explicit, so the reviewer checks whether Q loaded the +required data and whether the code handles a real NULL appropriately. +Unloaded access produces the language-specific diagnostic; a NULL fallback +is not permission to ignore an unloaded property. + +## Mutation API keeps changes behind one Save boundary -## Change the object and save +The application declares the change and its reason instead of writing its own +persistence loop. A graph can stage additions, updates and deletions before Save. Load the complete scalar fields of every persisted object you actually modify. A display-only partial projection is not a complete mutation input. Unmodified @@ -104,25 +135,51 @@ approval emits a warning; it is not automatic rejection. Marking for deletion stages a change—the audited Save performs it. Atomicity is provider/route scoped, not a distributed transaction across unrelated databases. -## See why an operation happened +## Automatic logs without handwritten logging code + +**Debuggability and operability are core design goals.** The Q and Save +examples above contain no logging calls: you declare the business intent, +and the runtime produces the execution diagnostics and trace context. +Configured audit sinks receive change events without each application +method having to construct its own field-level diff. + +The intent declarations already belong to the business operation: + +- `comment` describes what the query does. +- `purpose` explains why it runs. +- `auditAs` gives the reason for a saved change. + +No-code logging means no handwritten logger calls in each business method, +not an application without code or intent declarations. Runtime startup +still configures any required sink; custom formats and destinations use the +logging extension points rather than edits to every business operation. + +- **Debugging:** connect a query's intent to generated SQL, execution outcome + and the trace path when a screen or business operation behaves unexpectedly. +- **Operations:** follow query and mutation activity and use audit reasons + and safely exposed changes to investigate incidents. +- **Review:** inspect the business operation without separately checking + that every TeaQL execution path has a matching application logging statement. Query and Mutation diagnostic logs are enabled by default and can be switched off independently. Logging off does not disable intent validation or Policy. -Intent, physical SQL paths and mutation responsibility are separate facts. -For example, a safe diagnostic can tell an operator which query populated a -screen, and an audit can explain why a saved object changed. - -Illustrative, shortened view—not a literal logger format or a benchmark result: +Illustrative, shortened view of the rename operation, not a literal logger +format or a captured test result; the SQL excerpt omits additional selected fields: ```text query entity=School comment="load the reviewed object" purpose="edit form" outcome=success -SQL: SELECT id, version FROM school_data WHERE id = 42; +SQL: SELECT id, version, name FROM school_data WHERE id = 42; trace: School -> request -> sqlite -> select mutation entity=School auditReason="Rename the reviewed school" outcome=committed +change: name "Riverside Primary School" -> "Riverside Academy" lineage: School#42("Rename the reviewed school") ``` +The declarations explain **why**; SQL and audit evidence show **what happened**. +Together they help locate the relevant operation without reconstructing the +entire call path from scattered application code. + SQL execution stays parameterized. Diagnostic SQL has parameters substituted after field-aware masking; it is not a question-mark template you must manually reconstruct. Ordinary bindings stay visible, sensitive bindings use the shared @@ -131,6 +188,81 @@ is labeled `MASKED; NOT REPLAYABLE`; SQL that cannot be safely rendered is omitt Application mutation audits are delivered after commit and discarded on rollback. This is not a durable audit outbox. Do not put secrets in comment or purpose. +## Discover only the API needed next + +A coding agent does not need every generated method in its context. Start with +the generated application's `AGENTS.md` and workspace guidance, request an +entity/action Assist, then ask for field-specific help only for the field +being used. + +For a model in `models/`, the Java query path is: + +```bash +cargo teaql java-assist-query/school --input models/ +cargo teaql java-assist-query/school.established_date --input models/ +``` + +These commands call the model-aware service; the model must match the generated +library. Assist uses canonical KSML entity and field names, even when the +language-native API uses a different naming style. Cargo TeaQL is a service +client for multiple languages, not just Rust. + +Use Assist to discover operations instead of reading generated library source +or guessing names. If the required operation is missing, report +`MISSING_ASSIST` rather than inventing an API. The +[Agent Kit](https://github.com/teaql/teaql-agent-kit) defines this progressive +workflow. Library and runtime maintenance are separate from application coding. + +## Software checks complement agent instructions + +AI proposes the model and application logic; software checks the parts that +can be verified mechanically. The library is one part of the TeaQL harness, +not a replacement for business review. + +| Stage | TeaQL support | Feedback to inspect | +| --- | --- | --- | +| Model and repair | Semantic model evaluation | Errors, warnings and repair guidance | +| Generate | Domain library combined with this runtime | Language tooling checks the generated API contract | +| Customize the workspace | Progressive Assist, Q, E and mutation APIs | Build diagnostics, Checker and configured Policy results | +| Verify and operate | Tests, runtime startup, intent and audit evidence | Actual outcomes, remaining failures and execution paths | + +Build checks verify API use, not whether the business decision is right. +Tests must still verify the application's behavior. A prompt, successful +generation or a clean build alone does not prove the finished application correct. + +## Try it with your coding agent + +You can start with an agent you already use. Paste this prompt: + +```text +Follow the current instructions at https://github.com/teaql/teaql-agent-kit. +Build a small school-management application in Java using SQLite. +Evaluate and repair the model, generate the domain library and prepare a runnable +application workspace. Verify Q, E, Checker and audited Save. +Finish with a report of commands, results and +remaining frictions. Include Q/E examples and relevant intent/audit logs. +Do not claim token savings without a measured comparison. +``` + +The [Agent Kit](https://github.com/teaql/teaql-agent-kit) guides modeling, +evaluation/repair, generation and application customization. It may install +toolchains and download dependencies; review installation permissions and the +final execution report. It is a workflow, not a guarantee of unattended correctness. + +## Run the local example + +Java 17+ and Maven 3.8+. From a checkout of this repository: + +```bash +bash examples/verify-runtime-examples.sh +``` + +The [School example](examples/school-management/README.md) +exercises SQLite schema/bootstrap and generated application APIs against this +repository's local runtime. No external database server or generator is needed +to run the retained generated example. Use only the example's test database; +reset/repeated-run behavior is documented in its README. + ## Use the published runtime Current documented runtime: **1.554-RELEASE**. Keep domain-library and runtime