philipgreat · Oct 13, 2026 · Oct 13, 2026 · Oct 13, 2026 · Oct 13, 2026 · Oct 13, 2026
diff --git a/.github/workflows/example-gate.yml b/.github/workflows/example-gate.yml
@@ -9,6 +9,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+      - name: Install example verification tools
+        run: sudo apt-get update && sudo apt-get install -y ripgrep
       - uses: actions/setup-java@v4
         with:
           distribution: temurin

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.555-RELEASE] - 2026-10-13
+
+Tracking: [Java #209](https://github.com/teaql/teaql-java/issues/209) and
+[conformance #109](https://github.com/teaql/teaql-conformance/issues/109).
+
+- Add the optional `teaql-opentelemetry` standard module with trusted environment
+  activation, startup guidance and full safe traces, metrics and logs.
+- Preserve expanded masked SQL, carried physical execution identity, request-tree
+  comments and independent graph mutation audit. No per-method SDK setup is needed.
+- Bound queued/exporting work, acknowledge receiver rejection separately from
+  failed batches, and preserve business outcomes during finite shutdown/export failure.
+- Retire the separate page terminal; regenerate libraries and use ordinary list
+  execution with offset/limit and explicit count where needed.
+
+Source and internal-candidate evidence is retained in the conformance
+`2026-10-13-standard-telemetry-onboarding` report. Signed-tag and final public
+artifact verification remain separate release gates.
+
 ## [1.526-RELEASE] - 2025-07-25
 
 ### Added

diff --git a/examples/business-id-runtime/pom.xml b/examples/business-id-runtime/pom.xml
@@ -6,7 +6,7 @@
     <parent>
         <groupId>io.teaql</groupId>
         <artifactId>teaql-java-parent</artifactId>
-        <version>1.554-RELEASE</version>
+        <version>1.555-RELEASE</version>
         <relativePath>../../pom.xml</relativePath>
     </parent>
     <artifactId>teaql-business-id-example</artifactId>

diff --git a/examples/conformance/lib/pom.xml b/examples/conformance/lib/pom.xml
@@ -12,7 +12,7 @@
   <properties>
     <java.version>21</java.version>
     <spring-boot.version>4.1.1</spring-boot.version>
-    <teaql.version>1.554-RELEASE</teaql.version>
+    <teaql.version>1.555-RELEASE</teaql.version>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
     <maven.compiler.parameters>true</maven.compiler.parameters>
   </properties>

diff --git a/examples/conformance/pom.xml b/examples/conformance/pom.xml
@@ -16,7 +16,7 @@
     <libversion>1.0.0</libversion>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
     <maven.compiler.parameters>true</maven.compiler.parameters>
-    <teaql.version>1.554-RELEASE</teaql.version>
+    <teaql.version>1.555-RELEASE</teaql.version>
   </properties>
 
   <repositories>

diff --git a/examples/order-management/java-app-console/pom.xml b/examples/order-management/java-app-console/pom.xml
@@ -11,7 +11,7 @@
   <properties>
     <maven.compiler.release>21</maven.compiler.release>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-    <teaql.version>1.554-RELEASE</teaql.version>
+    <teaql.version>1.555-RELEASE</teaql.version>
   </properties>
   <dependencies>
     <dependency>

diff --git a/examples/order-management/java-lib-core/lib/pom.xml b/examples/order-management/java-lib-core/lib/pom.xml
@@ -12,7 +12,7 @@
   <properties>
     <java.version>21</java.version>
     <spring-boot.version>4.1.1</spring-boot.version>
-    <teaql.version>1.554-RELEASE</teaql.version>
+    <teaql.version>1.555-RELEASE</teaql.version>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
     <maven.compiler.parameters>true</maven.compiler.parameters>
   </properties>

diff --git a/examples/round-trip-reference-runtime/pom.xml b/examples/round-trip-reference-runtime/pom.xml
@@ -6,7 +6,7 @@
     <parent>
         <groupId>io.teaql</groupId>
         <artifactId>teaql-java-parent</artifactId>
-        <version>1.554-RELEASE</version>
+        <version>1.555-RELEASE</version>
         <relativePath>../../pom.xml</relativePath>
     </parent>
     <artifactId>teaql-round-trip-reference-example</artifactId>

diff --git a/examples/school-management/lib/pom.xml b/examples/school-management/lib/pom.xml
@@ -12,7 +12,7 @@
   <properties>
     <java.version>21</java.version>
     <spring-boot.version>4.1.1</spring-boot.version>
-    <teaql.version>1.554-RELEASE</teaql.version>
+    <teaql.version>1.555-RELEASE</teaql.version>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
     <maven.compiler.parameters>true</maven.compiler.parameters>
   </properties>

diff --git a/examples/school-management/pom.xml b/examples/school-management/pom.xml
@@ -16,7 +16,7 @@
     <libversion>0.0.1-SNAPSHOT</libversion>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
     <maven.compiler.parameters>true</maven.compiler.parameters>
-    <teaql.version>1.554-RELEASE</teaql.version>
+    <teaql.version>1.555-RELEASE</teaql.version>
   </properties>
 
   <repositories>

diff --git a/...l-management/src/main/java/com/example/schoolmanagementservice/RequestIntentVerifier.java b/...l-management/src/main/java/com/example/schoolmanagementservice/RequestIntentVerifier.java
@@ -41,7 +41,7 @@ static void verify(TeaQLRuntime original) {
       required("REQUEST_COMMENT_REQUIRED", () -> runtime.executeForList(context, Q.schools()));
       required("REQUEST_COMMENT_REQUIRED", () -> runtime.executeForStream(context, Q.schools()));
       required("REQUEST_COMMENT_REQUIRED", () -> runtime.aggregation(context, Q.schools()));
-      required("REQUEST_COMMENT_REQUIRED", () -> runtime.executeForPage(context, Q.schools(), 0, 10));
+      required("REQUEST_COMMENT_REQUIRED", () -> runtime.executeForList(context, Q.schools().offset(0, 10).count()));
       required("QUERY_PURPOSE_REQUIRED", () -> runtime.executeForList(context, Q.schools().comment("load schools")));
       require(queryPolicyCalls.get() == 0 && statements.isEmpty(), "Invalid query reached policy or SQL");
       for (String blank : new String[]{"", " \t\r\n", "\u2003", "\u00a0"}) {

diff --git a/examples/security-foundations/pom.xml b/examples/security-foundations/pom.xml
@@ -6,7 +6,7 @@
     <parent>
         <groupId>io.teaql</groupId>
         <artifactId>teaql-java-parent</artifactId>
-        <version>1.554-RELEASE</version>
+        <version>1.555-RELEASE</version>
         <relativePath>../../pom.xml</relativePath>
     </parent>
     <artifactId>teaql-security-foundations-example</artifactId>

diff --git a/examples/shared-load-state/pom.xml b/examples/shared-load-state/pom.xml
@@ -3,7 +3,7 @@
          xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
   <modelVersion>4.0.0</modelVersion>
   <parent>
-    <groupId>io.teaql</groupId><artifactId>teaql-java-parent</artifactId><version>1.554-RELEASE</version>
+    <groupId>io.teaql</groupId><artifactId>teaql-java-parent</artifactId><version>1.555-RELEASE</version>
     <relativePath>../../pom.xml</relativePath>
   </parent>
   <artifactId>shared-load-state-example</artifactId>

diff --git a/...tate/src/test/java/com/example/schoolmanagementservice/GeneratedPageStreamAcceptance.java b/...tate/src/test/java/com/example/schoolmanagementservice/GeneratedPageStreamAcceptance.java
@@ -9,11 +9,13 @@
 final class GeneratedPageStreamAcceptance {
     static void verify(UserContext context, String first, String second) {
         var left = Q.schoolsWithMinimalFields().withNameIn(first,second).selectName().orderByIdAscending()
+                .offset(0,1).count()
                 .comment("what: load the first matching School page").purpose("why: qualify sparse page hydration")
-                .executeForPage(context,0,1);
+                .executeForList(context);
         var right = Q.schoolsWithMinimalFields().withNameIn(first,second).selectName().orderByIdAscending()
+                .offset(1,1).count()
                 .comment("what: load the second matching School page").purpose("why: qualify adjacent pages and filtered total")
-                .executeForPage(context,1,1);
+                .executeForList(context);
         assertEquals(2,left.getTotalCount());assertEquals(2,right.getTotalCount());
         assertEquals(1,left.size());assertEquals(1,right.size());
         assertNotEquals(left.first().getId(),right.first().getId());

diff --git a/examples/standard-order/AGENTS.md b/examples/standard-order/AGENTS.md
@@ -0,0 +1,27 @@
+# Java Standard Order Example Rules
+
+Implement only application-owned code. The files under `generated/lib` are
+read-only. Discover generated APIs using progressive model-aware Assist with
+`models/model.xml`; never read generated source to discover methods.
+
+```bash
+cargo teaql --input models/model.xml java-assist-query/customer_order
+cargo teaql --input models/model.xml java-assist-query/customer_order.order_item_list
+```
+
+Use bounded Q queries through one trusted UserContext, with non-empty comment
+and purpose. Configure offset/limit on the request and execute through
+`executeForList(context)`. Do not introduce a separate `executeForPage` entry.
+Requested count, facet and relationship metadata belong to the returned
+SmartList. Use generated E for loaded-value traversal and preserve NotLoaded
+as an error.
+
+Use generated audited mutation APIs for seed data; do not handwrite INSERTs.
+Runtime, providers and policy are assembled once. Standard telemetry is selected
+by trusted environment settings; business methods contain no SDK initialization
+or manually created spans. Ordinary SQL output and telemetry are independent.
+
+Verify against repository-local Maven reactor modules. Run `bash verify.sh` and
+retain startup messages, results and generated-library hashes. Backend delivery
+is verified separately by conformance's controlled capture. Do not claim export
+success merely because the application exits successfully.
diff --git a/examples/standard-order/README.md b/examples/standard-order/README.md
@@ -0,0 +1,43 @@
+# Java Standard Telemetry Order Example
+
+This example uses generated Q/E and the ordinary `executeForList(context)`
+entry point to load a filtered order list with bounded pagination, status
+details, child previews, child counts and status facets. No business method
+initializes an SDK or creates a span.
+
+The five-object model seeds one Platform and three status constants through
+generated audited mutations. Repeated ensureSchema does not produce duplicate
+writes or audits. Four orders and twenty items are created through the same
+mutation API. The filtered result contains three orders; the selected one-row
+slice has three item previews and an independent count of five items. Status
+facets have counts `1, 2, 0` and amount totals `100, 500, 0`. The deliberately
+omitted order amount remains NotLoaded.
+
+The local runtime handles a declared ungrouped count alongside rows under one
+logical list invocation. Grouped and mixed aggregate requests keep their
+existing aggregate semantics. All generated library files are produced from
+the checked model; do not patch them to change query behavior.
+
+Run the local application acceptance twice, with startup guidance and unchanged
+generated-library hashes:
+
+```bash
+bash examples/standard-order/verify.sh
+```
+
+The optional standard module enables all supported signals with these trusted
+process settings:
+
+```bash
+TEAQL_TELEMETRY_ENABLED=true \
+TEAQL_TELEMETRY_SERVICE_NAME=order-example \
+TEAQL_TELEMETRY_OTLP_ENDPOINT=http://127.0.0.1:4318 \
+  mvn -q -Pruntime-examples -pl examples/standard-order -am \
+    -Dtest=StandardOrderTelemetryTest -Dsurefire.failIfNoSpecifiedTests=false test
+```
+
+Ordinary SQL logs are disabled in the example. The checked model marks order
+numbers and customer names for masking; telemetry must still export safe
+expanded SQL. Conformance's `telemetry/capture-java-standard-order.cjs` checks
+actual backend delivery and parentage. A successful application run alone does
+not establish that all SQL diagnostics reached the collector.
diff --git a/examples/standard-order/generated/lib/pom.xml b/examples/standard-order/generated/lib/pom.xml
@@ -0,0 +1,142 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <groupId>com.example</groupId>
+  <artifactId>request-tree-order-service-core</artifactId>
+  <version>0.0.1-SNAPSHOT</version>
+  <packaging>jar</packaging>
+
+  <properties>
+    <java.version>21</java.version>
+    <spring-boot.version>4.1.1</spring-boot.version>
+    <teaql.version>1.555-RELEASE</teaql.version>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    <maven.compiler.parameters>true</maven.compiler.parameters>
+  </properties>
+
+  <repositories>
+    <repository>
+      <id>teaql</id>
+      <url>https://maven.teaql.io/repository/maven-releases/</url>
+    </repository>
+  </repositories>
+
+  <dependencyManagement>
+    <dependencies>
+      <dependency>
+        <groupId>org.springframework.boot</groupId>
+        <artifactId>spring-boot-dependencies</artifactId>
+        <version>${spring-boot.version}</version>
+        <type>pom</type>
+        <scope>import</scope>
+      </dependency>
+      <dependency>
+        <groupId>org.apache.tomcat.embed</groupId>
+        <artifactId>tomcat-embed-core</artifactId>
+        <version>11.0.26</version>
+      </dependency>
+      <dependency>
+        <groupId>org.apache.tomcat.embed</groupId>
+        <artifactId>tomcat-embed-el</artifactId>
+        <version>11.0.26</version>
+      </dependency>
+      <dependency>
+        <groupId>org.apache.tomcat.embed</groupId>
+        <artifactId>tomcat-embed-websocket</artifactId>
+        <version>11.0.26</version>
+      </dependency>
+    </dependencies>
+  </dependencyManagement>
+
+  <dependencies>
+    <dependency>
+      <groupId>org.springframework.boot</groupId>
+      <artifactId>spring-boot-autoconfigure</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.springframework.boot</groupId>
+      <artifactId>spring-boot-starter-web</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.springframework</groupId>
+      <artifactId>spring-tx</artifactId>
+    </dependency>
+        <dependency>
+          <groupId>io.teaql</groupId>
+          <artifactId>teaql-sqlite</artifactId>
+          <version>1.555-RELEASE</version>
+        </dependency>
+    <dependency>
+      <groupId>io.teaql</groupId>
+      <artifactId>teaql-core</artifactId>
+      <version>${teaql.version}</version>
+    </dependency>
+    <dependency>
+      <groupId>io.teaql</groupId>
+      <artifactId>teaql-runtime</artifactId>
+      <version>${teaql.version}</version>
+    </dependency>
+    <dependency>
+      <groupId>cn.hutool</groupId>
+      <artifactId>hutool-all</artifactId>
+      <version>5.8.20</version>
+    </dependency>
+  </dependencies>
+
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-compiler-plugin</artifactId>
+        <version>3.12.1</version>
+        <configuration>
+          <release>${java.version}</release>
+          <parameters>${maven.compiler.parameters}</parameters>
+        </configuration>
+      </plugin>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-enforcer-plugin</artifactId>
+        <version>3.5.0</version>
+        <executions>
+          <execution>
+            <id>enforce-java-version</id>
+            <goals>
+              <goal>enforce</goal>
+            </goals>
+            <configuration>
+              <rules>
+                <requireJavaVersion>
+                  <version>[${java.version},)</version>
+                </requireJavaVersion>
+              </rules>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-source-plugin</artifactId>
+        <version>3.3.0</version>
+        <executions>
+          <execution>
+            <id>attach-sources</id>
+            <goals>
+              <goal>jar-no-fork</goal>
+            </goals>
+          </execution>
+        </executions>
+      </plugin>
+    </plugins>
+  </build>
+
+  <distributionManagement>
+    <repository>
+      <id>target-repo</id>
+      <url>https://maven.teaql.io/repository/maven-releases/</url>
+    </repository>
+  </distributionManagement>
+</project>
diff --git a/...rated/lib/src/main/java/com/example/requesttreeorderservice/BaseServiceConfiguration.java b/...rated/lib/src/main/java/com/example/requesttreeorderservice/BaseServiceConfiguration.java
diff --git a/...ndard-order/generated/lib/src/main/java/com/example/requesttreeorderservice/Checkers.java b/...ndard-order/generated/lib/src/main/java/com/example/requesttreeorderservice/Checkers.java
diff --git a/...dard-order/generated/lib/src/main/java/com/example/requesttreeorderservice/Constants.java b/...dard-order/generated/lib/src/main/java/com/example/requesttreeorderservice/Constants.java
@@ -0,0 +1,14 @@
+
+package com.example.requesttreeorderservice;
+
+import com.example.requesttreeorderservice.orderstatus.OrderStatus;
+import com.example.requesttreeorderservice.platform.Platform;
+
+public interface Constants  {
+  public static final long PLATFORM_ID = 1l;
+  public static final Platform PLATFORM = Platform.refer(PLATFORM_ID);
+  public static final long ORDER_STATUS_NEW_ID = 1001l ;
+  public static final OrderStatus ORDER_STATUS_NEW = OrderStatus.refer(ORDER_STATUS_NEW_ID);public static final long ORDER_STATUS_PAID_ID = 1002l ;
+  public static final OrderStatus ORDER_STATUS_PAID = OrderStatus.refer(ORDER_STATUS_PAID_ID);public static final long ORDER_STATUS_CANCELLED_ID = 1003l ;
+  public static final OrderStatus ORDER_STATUS_CANCELLED = OrderStatus.refer(ORDER_STATUS_CANCELLED_ID);
+}