Cross-language Mutation Lifecycle

TeaQL's Mutation API covers create, update, deletion intent, recovery, audit, and graph save. “Update API” is not a separate canonical family: generated field updates participate in the same Mutation lifecycle.

For the operation chooser and native examples in all seven languages, start at Query, Mutation, Analytics, and Facets.

One graph, one mutation boundary

Every queried or newly created object graph has an independent logical Mutation Ledger. Entities explicitly composed into that graph share the ledger. UserContext supplies trusted services and contextual values, but it must not own or merge pending mutations from unrelated graphs.

Generated field updates change the language object and record the final value under the canonical KSML property identity. Provider column names and language-native member casing do not change that identity.

Create and update

Create allocates identity before returning the new entity. Update begins from current loaded state and preserves the original optimistic version. Both flows:

1. use generated allow-listed mutation methods;
2. run context-derived Fix and Checker before provider mutation;
3. attach a non-empty audit reason;
4. commit through ordinary save(context) semantics;
5. return authoritative persisted entity state and version.

A failed or rejected save retains enough pending state for a controlled retry and must not leave committed in-memory identity/version side effects.

Deletion is intent, not a second commit API

The public operation records pending deletion using idiomatic spelling:

Runtime	Generated deletion intent
Java, TypeScript, Swift	markForDeletion()
Rust, Python	mark_for_deletion()
.NET, Go	MarkForDeletion()

It does not receive context or call a provider. The audited graph save(context) boundary may atomically commit created, updated, and deletion-marked entities together. Public delete-with-context convenience methods would create a second persistence boundary and are nonconforming.

Checker and Fix

Fix can derive trusted values such as context-owned roots before validation. Checker returns structured, field-specific locations and stops invalid graphs before the first provider/SQL mutation. Database constraints remain defense in depth; they do not replace generated friendly validation.

Identity is a separate concern

Portable internal Entity ID allocation is aligned across seven runtimes. Aggregate-root Business ID generation has a narrower current evidence boundary and must be reported separately. See Cross-language Conformance Status instead of inferring Business ID support from Entity ID behavior.

Use the language guides for native methods and Audit-ready Mutation for an application recipe.