examples: demonstrate customer mutation policy

Author: Philip Z

examples/order-management/README.md

@@ -8,7 +8,12 @@ mvn -q install -DskipTests
 mvn -q exec:java -pl java-app-console
 ```
 
-The first run creates `.local/order.db`, ensures schema from generated metadata, seeds through generated entities, performs a governed query, and saves an audited preset. The second run demonstrates idempotency.
+The first run creates `.local/order.db`, ensures schema from generated metadata,
+seeds through generated entities, performs a governed query, and saves an
+audited preset. It also installs a customer-owned `OrderMutationPolicy`, denies
+an unauthorized high-value order as one complete graph, and queries SQLite to
+prove that zero order rows were written. The second run demonstrates
+idempotency and repeats the policy proof.
 
 Read `java-app-console/.../OrderManagementApp.java` first (handwritten), then `java-lib-core/lib/.../Q.java`, `CustomerOrderRequest.java`, and `CustomerOrder.java` (generated). Java is the naming and governance gold standard: `comment(...)` may appear anywhere before `purpose(...)`; only the purposed request exposes execute methods.
 
@@ -19,6 +24,25 @@ Expect one `WEB-2026-001` row dated `2026-08-12` with amount `129.95`. The first
 ## Customize it
 
 Change the `withOrderNumberContaining` filter, ordering, or projection in the app and rerun. Add business behavior only under `java-app-console`; regenerate everything under `java-lib-core`. This library was generated from the shared Order Management model used by the six-language example suite, but that model and the generator are not runtime prerequisites.
+
+### Customize whole-graph mutation policy
+
+`OrderMutationPolicy.java` is application-owned code. It reviews the immutable
+`MutationPlan` after Checker/Fix and graph assembly but before the first
+provider write. The example requires a trusted `MutationAuthority` capability
+for orders above `10000.00` and returns the stable denial code
+`ORDER-HIGH-VALUE-AUTHORITY-REQUIRED` when that authority is absent.
+
+`OrderManagementApp.context(...)` shows the three customer configuration
+points:
+
+1. register policy by the stable `CustomerOrder.saveGraph` request key;
+2. provide approval for the exact policy identity and fingerprint;
+3. install trusted request authority in `UserContext`, outside remote input.
+
+Change the installed permission set to
+`Set.of(OrderMutationPolicy.HIGH_VALUE_PERMISSION)` to exercise the allowed
+path. Do not place trusted authority in request JSON or generated entities.
 ### Materialized-list hard limit
 
 `executeForList` protects the service by applying a default hard limit of 10,000 rows. A requested page size above that ceiling fails explicitly. Trusted application code can call `hardLimit(...)` to override the outer-query ceiling. **Caution:** most applications should not override it; do so only for a reviewed, exceptional requirement. This setting does not describe streaming execution.

examples/order-management/java-app-console/src/main/java/com/teaql/example/MutationAuthority.java

@@ -0,0 +1,14 @@
+package com.teaql.example;
+
+import java.util.Set;
+
+/** Trusted application authority installed in UserContext by server-side code. */
+public record MutationAuthority(Set<String> permissions) {
+    public MutationAuthority {
+        permissions = Set.copyOf(permissions == null ? Set.of() : permissions);
+    }
+
+    public boolean permits(String permission) {
+        return permissions.contains(permission);
+    }
+}

examples/order-management/java-app-console/src/main/java/com/teaql/example/OrderManagementApp.java

@@ -8,7 +8,9 @@
 import com.teaql.ordermanagementservice.ordersearchpreset.OrderSearchPreset;
 import io.teaql.core.DataServiceExecutor;
 import io.teaql.core.InternalIdGenerationService;
+import io.teaql.core.MutationPolicyApproval;
 import io.teaql.core.SmartList;
+import io.teaql.core.TeaQLRuntimeException;
 import io.teaql.core.UserContext;
 import io.teaql.core.meta.EntityMetaFactory;
 import io.teaql.core.meta.SimpleEntityMetaFactory;
@@ -24,7 +26,10 @@
 import java.sql.DriverManager;
 import java.sql.SQLException;
 import java.sql.SQLFeatureNotSupportedException;
+import java.time.Instant;
 import java.time.LocalDate;
+import java.util.Optional;
+import java.util.Set;
 import java.util.concurrent.atomic.AtomicLong;
 import java.util.logging.Logger;
 import javax.sql.DataSource;
@@ -97,6 +102,8 @@ public static void main(String[] args) throws Exception {
             preset.auditAs("Save idempotent quick-start search preset").save(context);
             System.out.println("[mutation] saved preset #" + preset.getId());
         } else System.out.println("[mutation] preset #" + presets.get(0).getId() + " already exists");
+
+        demonstrateMutationPolicy(context, platform);
     }
 
     private static UserContext context(DataServiceExecutor executor) {
@@ -105,10 +112,61 @@ private static UserContext context(DataServiceExecutor executor) {
         EntityMetaFactory.registerGlobal(metadata);
         AtomicLong ids = new AtomicLong(1000);
         InternalIdGenerationService idGeneration = (context, entity) -> ids.getAndIncrement();
+        OrderMutationPolicy orderPolicy = new OrderMutationPolicy();
         TeaQLRuntime runtime = TeaQLRuntime.builder().metadata(metadata)
                 .dataService("default", executor).dataService("sqlite", executor)
-                .idGenerationService(idGeneration).build();
-        return new DefaultUserContext(runtime);
+                .idGenerationService(idGeneration)
+                .mutationPolicyRegistry(requestKey -> "CustomerOrder.saveGraph".equals(requestKey)
+                        ? Optional.of(orderPolicy)
+                        : Optional.empty())
+                .mutationPolicyApprovalProvider(identity -> identity.equals(orderPolicy.identity())
+                        ? Optional.of(new MutationPolicyApproval(
+                                identity,
+                                "example-security-review",
+                                Instant.parse("2026-09-29T12:00:00Z")))
+                        : Optional.empty())
+                .build();
+        DefaultUserContext context = new DefaultUserContext(runtime);
+        context.putAttribute(
+                MutationAuthority.class.getName(), new MutationAuthority(Set.of()));
+        return context;
+    }
+
+    private static void demonstrateMutationPolicy(
+            UserContext context, CommercePlatform platform) {
+        String rejectedOrderNumber = "WEB-2026-HIGH-VALUE-DENIED";
+        Customer rejectedCustomer = new Customer()
+                .updateName("Rejected High Value Customer")
+                .updateEmail("not-persisted@example.invalid")
+                .updateCommercePlatform(platform);
+        CustomerOrder rejectedOrder = new CustomerOrder()
+                .updateOrderNumber(rejectedOrderNumber)
+                .updateOrderDate(LocalDate.of(2026, 9, 29))
+                .updateTotalAmount(new BigDecimal("25000.00"))
+                .updateStatusToPending()
+                .updateCustomer(rejectedCustomer)
+                .updateCommercePlatform(platform);
+
+        try {
+            rejectedOrder.auditAs("Demonstrate customer high-value order policy")
+                    .save(context);
+            throw new IllegalStateException("The high-value mutation should have been denied");
+        } catch (TeaQLRuntimeException expected) {
+            if (!expected.getMessage().contains("ORDER-HIGH-VALUE-AUTHORITY-REQUIRED")) {
+                throw expected;
+            }
+        }
+
+        SmartList<CustomerOrder> rejectedRows = Q.customerOrders()
+                .withOrderNumberIs(rejectedOrderNumber)
+                .comment("Verify the denied high-value graph wrote no order")
+                .purpose("Prove customer MutationPolicy denial is atomic")
+                .executeForList(context);
+        if (!rejectedRows.isEmpty()) {
+            throw new IllegalStateException("Denied high-value order was persisted");
+        }
+        System.out.println(
+                "[mutation-policy] denied high-value graph before persistence; verified 0 order rows");
     }
 
     private record DriverManagerDataSource(String url) implements DataSource {

examples/order-management/java-app-console/src/main/java/com/teaql/example/OrderMutationPolicy.java

@@ -0,0 +1,48 @@
+package com.teaql.example;
+
+import io.teaql.core.MutationDecision;
+import io.teaql.core.MutationOperationKind;
+import io.teaql.core.MutationPlan;
+import io.teaql.core.MutationPolicy;
+import io.teaql.core.MutationPolicyIdentity;
+import io.teaql.core.UserContext;
+import java.math.BigDecimal;
+import java.util.List;
+
+/** Customer-owned whole-graph policy for the order-management example. */
+public final class OrderMutationPolicy implements MutationPolicy {
+    public static final String HIGH_VALUE_PERMISSION = "order.submitHighValue";
+    public static final BigDecimal HIGH_VALUE_THRESHOLD = new BigDecimal("10000.00");
+    public static final MutationPolicyIdentity IDENTITY = new MutationPolicyIdentity(
+            "example.order-mutation", "1.0.0", "example:order-policy-2026-09-29");
+
+    @Override
+    public MutationPolicyIdentity identity() {
+        return IDENTITY;
+    }
+
+    @Override
+    public MutationDecision review(UserContext context, MutationPlan plan) {
+        boolean containsHighValueOrder = plan.operations().stream()
+                .filter(operation -> operation.kind() == MutationOperationKind.CREATE
+                        || operation.kind() == MutationOperationKind.UPDATE)
+                .map(operation -> operation.changedValues().get("totalAmount"))
+                .filter(BigDecimal.class::isInstance)
+                .map(BigDecimal.class::cast)
+                .anyMatch(amount -> amount.compareTo(HIGH_VALUE_THRESHOLD) > 0);
+
+        if (!containsHighValueOrder) {
+            return MutationDecision.allow();
+        }
+
+        MutationAuthority authority = context.capability(MutationAuthority.class);
+        if (authority != null && authority.permits(HIGH_VALUE_PERMISSION)) {
+            return MutationDecision.allow();
+        }
+
+        return MutationDecision.deny(
+                "ORDER-HIGH-VALUE-AUTHORITY-REQUIRED",
+                "Orders above 10000.00 require the high-value order authority",
+                List.of("totalAmount"));
+    }
+}