diff --git a/.github/workflows/example-gate.yml b/.github/workflows/example-gate.yml
index 5c69f2892..5da0c01ac 100644
--- a/.github/workflows/example-gate.yml
+++ b/.github/workflows/example-gate.yml
@@ -7,13 +7,37 @@ on:
jobs:
examples:
runs-on: ubuntu-latest
+ permissions:
+ contents: read
+ defaults:
+ run:
+ working-directory: runtime
env:
+ TEAQL_CODEGEN_DIR: ${{ github.workspace }}/generator
TEAQL_S3_ENDPOINT: http://127.0.0.1:19010
TEAQL_S3_BUCKET: teaql-java-example-ci
TEAQL_S3_ACCESS_KEY: teaql-java-example-ci
TEAQL_S3_SECRET_KEY: teaql-java-example-ci-fixture-only
steps:
- - uses: actions/checkout@v4
+ - name: Check out runtime under test
+ uses: actions/checkout@v4
+ with:
+ path: runtime
+ persist-credentials: false
+ # This key is a read-only deploy key on this one private repository,
+ # not a personal token. Fork PRs receive no repository secrets.
+ - name: Check out qualified generator
+ uses: actions/checkout@v4
+ with:
+ repository: teaql/teaql-code-gen
+ ref: 554a1b7fa1e5c053e52290c3ee48925901cebe00
+ path: generator
+ ssh-key: ${{ secrets.TEAQL_CODEGEN_READONLY_DEPLOY_KEY }}
+ persist-credentials: false
+ - name: Verify pinned generator source
+ run: |
+ test "$(git -C "$TEAQL_CODEGEN_DIR" rev-parse HEAD)" = 554a1b7fa1e5c053e52290c3ee48925901cebe00
+ test -z "$(git -C "$TEAQL_CODEGEN_DIR" status --porcelain)"
- name: Install example verification tools
run: sudo apt-get update && sudo apt-get install -y ripgrep
- uses: actions/setup-java@v4
@@ -21,6 +45,31 @@ jobs:
distribution: temurin
java-version: '21'
cache: maven
+ - name: Prime third-party dependencies for offline source-paired probes
+ # The gate copies third-party downloads into a disposable Maven home
+ # and explicitly excludes every TeaQL/model artifact from that cache.
+ # Keep its offline checks; prepare a fresh runner before they start.
+ run: |
+ mvn -B -ntp install
+ node <<'NODE'
+ const fs = require('node:fs'), path = require('node:path'), os = require('node:os'), cp = require('node:child_process');
+ const runtime = process.cwd(), owned = fs.mkdtempSync(path.join(os.tmpdir(), 'teaql-ci-example-dependencies-'));
+ try {
+ const poms = cp.execFileSync('git', ['ls-files', '-z', 'examples'], {encoding: 'utf8'})
+ .split('\0').filter(name => name.endsWith('/lib/pom.xml'));
+ if (poms.length === 0) throw new Error('No generated library dependency manifests');
+ for (const relative of poms) {
+ const selected = path.join(owned, relative);
+ fs.mkdirSync(path.dirname(selected), {recursive: true});
+ fs.copyFileSync(path.join(runtime, relative), selected);
+ require('./scripts/pin-local-example-pom.cjs').pin(selected, runtime, owned);
+ cp.execFileSync('mvn', ['-B', '-ntp', '-f', selected,
+ 'org.apache.maven.plugins:maven-dependency-plugin:3.8.1:go-offline'], {stdio: 'inherit'});
+ }
+ } finally {
+ fs.rmSync(owned, {recursive: true});
+ }
+ NODE
- name: Start dedicated S3 example fixture
run: |
docker run -d --name teaql-java-example-s3 \
diff --git a/examples/business-id-runtime/pom.xml b/examples/business-id-runtime/pom.xml
index a21961011..40fa63595 100644
--- a/examples/business-id-runtime/pom.xml
+++ b/examples/business-id-runtime/pom.xml
@@ -6,7 +6,7 @@
io.teaql
teaql-java-parent
- 1.555-RELEASE
+ 1.556-RELEASE
../../pom.xml
teaql-business-id-example
diff --git a/examples/conformance/README.md b/examples/conformance/README.md
index 83fe762de..020d82198 100644
--- a/examples/conformance/README.md
+++ b/examples/conformance/README.md
@@ -16,3 +16,53 @@ using an isolated temporary SQLite database for each run.
The generated Runtime Module is installed at application startup but remains a
passive manifest. Schema reconciliation is invoked separately and explicitly.
+
+## Generated Fix postconditions and safe provenance
+
+```bash
+node examples/fix-e-alignment/verify-local.cjs
+```
+
+The unchanged three-object model supplies a parent and child with required
+context-root references and create/update timestamps. Three additional
+application-owned tests assert typed managed defaults before validation,
+unchanged ordinary business inputs read back with generated Q/E, and exactly
+one immutable, value-free provenance entry per fixed field. Invalid required
+and range inputs fail after Fix with zero provider reads, writes or transactions;
+corrected input then saves in a fresh invocation. Both rounds use the same
+SQLite files without cleanup between them.
+
+`TEAQL_FIX_E_EVIDENCE_DIR` selects a new absolute directory for compact logs,
+hashes and databases. Build output is removed on exit. This proves the declared
+clock/root and ordinary required/range vectors, not arbitrary custom context
+fixers, a range-constrained generated default, security/TTL clock behavior or
+the complete seven-runtime diagnostic contract.
+
+## Caller-owned Spring transactions
+
+```bash
+node examples/conformance/spring-transactions/verify-local.cjs
+```
+
+This focused source-paired gate reuses the unchanged two-object generated library.
+Business operations use generated Q/E and audited Save, with an application-owned
+Spring `DataSourceTransactionManager` over a real SQLite file. Eight scenarios
+run twice on the same stores: sparse no-op plus outer commit; outer rollback and
+latest-intent retry; nested rollback; equal-position/repeated savepoints;
+`REQUIRES_NEW` isolation; post-commit audit delivery failure; pre-provider Checker
+and intent rejection; and an actual second graph-write failure followed by retry.
+Independent SQL is used only for readback and controlled trigger fault injection,
+not to implement application persistence. Audit observers verify committed rows
+through an independent connection, outside the completed Spring owner.
+
+Set `TEAQL_JAVA_SPRING_EVIDENCE_DIR` to a new absolute directory to retain compact
+logs, JUnit XML, hashes and databases there. Builds and isolated dependency copies
+are removed on exit; no TeaQL artifacts are borrowed from the Maven cache and no
+shared install/deploy is performed. `--baseline` executes the same application
+against the pre-fix `6d162bb0` production archive and intentionally exits nonzero
+when it reproduces a failed assertion; that is not a passing runtime gate.
+
+The complete example script includes this gate. This is SQLite plus Spring JDBC,
+not JTA/reactive/custom-manager or installed-artifact acceptance. The model has no
+Decimal field: exact Decimal registration for Spring-backed SQLite is a separate
+provider boundary, not implemented by a fake function in this example.
diff --git a/examples/conformance/lib/pom.xml b/examples/conformance/lib/pom.xml
index 7e2df1b40..8606fff55 100644
--- a/examples/conformance/lib/pom.xml
+++ b/examples/conformance/lib/pom.xml
@@ -12,7 +12,7 @@
21
4.1.1
- 1.555-RELEASE
+ 1.556-RELEASE
UTF-8
true
diff --git a/examples/conformance/pom.xml b/examples/conformance/pom.xml
index 492d0b693..4374ef62f 100644
--- a/examples/conformance/pom.xml
+++ b/examples/conformance/pom.xml
@@ -16,7 +16,7 @@
1.0.0
UTF-8
true
- 1.555-RELEASE
+ 1.556-RELEASE
diff --git a/examples/conformance/spring-transactions/GeneratedSpringTransactionTest.java b/examples/conformance/spring-transactions/GeneratedSpringTransactionTest.java
new file mode 100644
index 000000000..e83d231eb
--- /dev/null
+++ b/examples/conformance/spring-transactions/GeneratedSpringTransactionTest.java
@@ -0,0 +1,298 @@
+package com.teaql.runtimeexampleconformanceservice;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.teaql.runtimeexampleconformanceservice.platform.Platform;
+import com.teaql.runtimeexampleconformanceservice.workitem.WorkItem;
+import io.teaql.core.*;
+import io.teaql.core.checker.CheckException;
+import io.teaql.core.meta.SimpleEntityMetaFactory;
+import io.teaql.core.sqlite.SqliteDataServiceExecutor;
+import io.teaql.core.value.TeaQLNotLoadedException;
+import io.teaql.provider.springjdbc.SpringJdbcSqlExecutor;
+import io.teaql.runtime.*;
+import java.nio.file.Path;
+import java.sql.*;
+import java.util.*;
+import java.util.concurrent.atomic.AtomicLong;
+import org.junit.Test;
+import org.springframework.jdbc.core.namedparam.NamedParameterJdbcTemplate;
+import org.springframework.jdbc.datasource.DataSourceTransactionManager;
+import org.springframework.transaction.TransactionDefinition;
+import org.springframework.transaction.support.TransactionTemplate;
+import org.sqlite.Function;
+import org.sqlite.SQLiteDataSource;
+import static org.junit.Assert.*;
+
+/** Application-owned business calls. SQL below is an independent oracle/fault injector only. */
+public class GeneratedSpringTransactionTest {
+ static final class Context extends DefaultUserContext implements RuntimeExampleConformanceServiceUserContext {
+ Context(TeaQLRuntime runtime) { super(runtime); }
+ }
+
+ static final class Source extends SQLiteDataSource {
+ long connections;
+ final List written = new ArrayList<>(), rejected = new ArrayList<>();
+ @Override public Connection getConnection() throws SQLException {
+ connections++;
+ var connection = super.getConnection();
+ Function.create(connection, "spring_written", new Function() {
+ protected void xFunc() throws SQLException { written.add(value_long(0)); result(0); }
+ });
+ Function.create(connection, "spring_rejected", new Function() {
+ protected void xFunc() throws SQLException { rejected.add(value_long(0)); result(0); }
+ });
+ return connection;
+ }
+ }
+
+ static final class Fixture {
+ final int round = Integer.parseInt(System.getenv("TEAQL_SPRING_ROUND"));
+ final String kind, url;
+ final Source source = new Source();
+ final SpringJdbcSqlExecutor sql;
+ final DataSourceTransactionManager manager;
+ final List audits = new ArrayList<>();
+ final List policies = new ArrayList<>();
+ final Context context;
+ final Platform root;
+ boolean failDelivery;
+
+ Fixture(String kind) throws Exception {
+ this.kind = kind;
+ url = "jdbc:sqlite:" + Path.of(System.getenv("TEAQL_SPRING_DB_ROOT"), kind + ".sqlite").toAbsolutePath();
+ source.setUrl(url);
+ sql = new SpringJdbcSqlExecutor(new NamedParameterJdbcTemplate(source));
+ manager = new DataSourceTransactionManager(source);
+ var service = new SqliteDataServiceExecutor("sqlite", sql, source);
+ var ids = new AtomicLong(round * 1000L);
+ var policy = new MutationPolicy() {
+ public MutationPolicyIdentity identity() { return new MutationPolicyIdentity("spring-example", "1", "sha256:spring-example"); }
+ public MutationDecision review(UserContext caller, MutationPlan plan) { policies.add(plan); return MutationDecision.allow(); }
+ };
+ var runtime = TeaQLRuntime.builder().metadata(new SimpleEntityMetaFactory())
+ .dataService("default", service).dataService("sqlite", service)
+ .idGenerationService(new InternalIdGenerationService() {
+ public Long generateId(UserContext caller, Entity entity) { return ids.incrementAndGet(); }
+ public void ensureFloor(String type, long floor) { ids.accumulateAndGet(floor, Math::max); }
+ })
+ .executionLogging(false).mutationPolicyRegistry(key -> Optional.of(policy))
+ .logSink(new RuntimeLogSink() {
+ public void writeExecutionLog(UserContext caller, ExecutionMetadata event) {}
+ public void writeAuditEvent(UserContext caller, RawAuditEvent event) {
+ assertFalse("audit cannot reuse the completed physical owner", sql.hasActiveTransaction());
+ // A separate connection must observe committed data before delivery.
+ if (event.entityType().equals("WorkItem")) {
+ try { assertTrue(version((Long) event.entityId()) >= event.resultingVersion()); }
+ catch (SQLException error) { throw new IllegalStateException(error); }
+ }
+ audits.add(event);
+ if (failDelivery) throw new IllegalStateException("EXPECTED_AUDIT_DELIVERY_FAILURE");
+ }
+ }).build().install(GeneratedRuntimeModule.module());
+ context = new Context(runtime);
+ context.ensureSchema();
+ root = Q.platforms().withIdIs(1L).limit(1).comment("Load the system-provided root")
+ .purpose("Attach the Spring transaction example to its domain root").executeForOne(context);
+ assertNotNull(root);
+ var expected = Path.of(System.getProperty("teaql.expected.runtime.root")).toRealPath();
+ for (var type : List.of(BaseEntity.class, TeaQLRuntime.class, SpringJdbcSqlExecutor.class, SqliteDataServiceExecutor.class)) {
+ var origin = Path.of(type.getProtectionDomain().getCodeSource().getLocation().toURI()).toRealPath();
+ assertTrue("source-paired runtime origin: " + type.getName(), origin.startsWith(expected));
+ }
+ }
+
+ TransactionTemplate transaction(int propagation) {
+ var template = new TransactionTemplate(manager); template.setPropagationBehavior(propagation); return template;
+ }
+ TransactionTemplate transaction() { return transaction(TransactionDefinition.PROPAGATION_REQUIRED); }
+ WorkItem create(String title) {
+ return Q.workItems().comment("Prepare a Spring work item").purpose("Verify audited business persistence")
+ .newEntity(context).updatePlatform(root).updateTitle(title).updateDescription(null)
+ .auditAs("Seed the Spring transaction example").save(context);
+ }
+ WorkItem load(long id) {
+ return Q.workItems().withIdIs(id).limit(1).comment("Load every scalar field before mutation")
+ .purpose("Keep the original optimistic baseline").executeForOne(context);
+ }
+ long version(long id) throws SQLException {
+ try (var connection = DriverManager.getConnection(url);
+ var query = connection.prepareStatement("SELECT version FROM work_item_data WHERE id=?")) {
+ query.setLong(1, id); try (var rows = query.executeQuery()) { assertTrue(rows.next()); return rows.getLong(1); }
+ }
+ }
+ void oracle(long id, String title, String description, long version) throws SQLException {
+ try (var connection = DriverManager.getConnection(url);
+ var query = connection.prepareStatement("SELECT title,description,version,platform FROM work_item_data WHERE id=?")) {
+ query.setLong(1, id);
+ try (var rows = query.executeQuery()) {
+ assertTrue(rows.next()); assertEquals(title, rows.getString(1)); assertEquals(description, rows.getString(2));
+ assertEquals(version, rows.getLong(3)); assertEquals(root.getId().longValue(), rows.getLong(4)); assertFalse(rows.next());
+ }
+ }
+ }
+ void emit(Map observations) throws Exception {
+ var value = new LinkedHashMap(); value.put("passed", true); value.put("case", kind);
+ value.put("round", round); value.put("observations", observations);
+ var stored = new ArrayList