)","~(e?,e?)","~(h,0^?(h))>","a3?(h)","h(h)","a(a,a)","h(e?)","a(a)","0&()","M(p)","ai<~>(~)","aO(h)","@(@,h)","~(U,a)","X?(H,a,a,a,a)","a(H,a,a)","M(~())","a(H?,a,a)","a(as)","aq?(h)","@(@)","aj?(h)","@(h)","a(X,a,a)","M(@,aW)","a(a())","~(~(a,h,a),a,a,a,U)","~(a,@)","e(e,h,a)","a(a7,a,a,a,a)","a(a(a),a)","a(eQ,a)","a(eQ,a,a)","p()","ai(h)","e?(e?{parameter:aO})","e?(e?)","ap?(h)","a(X,U)","M(e,aW)"],interceptorsByTag:null,leafTags:null,arrayRti:Symbol("$ti"),rttc:{"2;":(a,b)=>c=>c instanceof A.cy&&a.b(c.a)&&b.b(c.b),"2;file,outFlags":(a,b)=>c=>c instanceof A.bF&&a.b(c.a)&&b.b(c.b),"2;result,resultCode":(a,b)=>c=>c instanceof A.cz&&a.b(c.a)&&b.b(c.b)}}
+A.lG(v.typeUniverse,JSON.parse('{"aB":"aT","dl":"aT","bg":"aT","nk":"aU","r":{"j":["1"],"i":["1"],"p":[],"f":["1"]},"d5":{"aO":[],"o":[]},"c1":{"o":[]},"c2":{"p":[]},"aT":{"p":[]},"d4":{"cf":[]},"ey":{"r":["1"],"j":["1"],"i":["1"],"p":[],"f":["1"]},"bR":{"K":["1"]},"bv":{"m":[],"a2":[],"t":["a2"]},"c0":{"m":[],"a":[],"a2":[],"t":["a2"],"o":[]},"d6":{"m":[],"a2":[],"t":["a2"],"o":[]},"aS":{"h":[],"t":["h"],"eI":[],"o":[]},"bx":{"q":[]},"i":{"f":["1"]},"V":{"i":["1"],"f":["1"]},"cn":{"V":["1"],"i":["1"],"f":["1"],"V.E":"1","f.E":"1"},"b9":{"K":["1"]},"bb":{"f":["2"],"f.E":"2"},"bV":{"bb":["1","2"],"i":["2"],"f":["2"],"f.E":"2"},"c6":{"K":["2"]},"a5":{"V":["2"],"i":["2"],"f":["2"],"V.E":"2","f.E":"2"},"cp":{"f":["1"],"f.E":"1"},"bh":{"K":["1"]},"bd":{"f":["1"],"f.E":"1"},"bW":{"bd":["1"],"i":["1"],"f":["1"],"f.E":"1"},"ch":{"K":["1"]},"ce":{"V":["1"],"i":["1"],"f":["1"],"V.E":"1","f.E":"1"},"cy":{"b0":[],"aH":[]},"bF":{"b0":[],"aH":[]},"cz":{"b0":[],"aH":[]},"bT":{"ba":["1","2"]},"bU":{"bT":["1","2"],"ba":["1","2"]},"cb":{"aE":[],"q":[]},"d8":{"q":[]},"dw":{"q":[]},"cA":{"aW":[]},"aP":{"b6":[]},"cS":{"b6":[]},"cT":{"b6":[]},"du":{"b6":[]},"dt":{"b6":[]},"br":{"b6":[]},"dr":{"q":[]},"c3":{"a_":["1","2"],"ba":["1","2"],"a_.K":"1","a_.V":"2"},"c5":{"i":["1"],"f":["1"],"f.E":"1"},"c4":{"K":["1"]},"eA":{"i":["1"],"f":["1"],"f.E":"1"},"b8":{"K":["1"]},"b0":{"aH":[]},"d7":{"l4":[],"eI":[]},"by":{"aU":[],"p":[],"o":[]},"aU":{"p":[],"o":[]},"c9":{"p":[]},"c7":{"ir":[],"p":[],"o":[]},"L":{"a4":["1"],"p":[]},"c8":{"k":["m"],"L":["m"],"j":["m"],"a4":["m"],"i":["m"],"p":[],"f":["m"],"T":["m"]},"a6":{"k":["a"],"L":["a"],"j":["a"],"a4":["a"],"i":["a"],"p":[],"f":["a"],"T":["a"]},"dc":{"k":["m"],"y":["m"],"L":["m"],"j":["m"],"a4":["m"],"i":["m"],"p":[],"f":["m"],"T":["m"],"o":[],"k.E":"m"},"dd":{"k":["m"],"y":["m"],"L":["m"],"j":["m"],"a4":["m"],"i":["m"],"p":[],"f":["m"],"T":["m"],"o":[],"k.E":"m"},"de":{"a6":[],"k":["a"],"y":["a"],"L":["a"],"j":["a"],"a4":["a"],"i":["a"],"p":[],"f":["a"],"T":["a"],"o":[],"k.E":"a"},"df":{"a6":[],"k":["a"],"y":["a"],"L":["a"],"j":["a"],"a4":["a"],"i":["a"],"p":[],"f":["a"],"T":["a"],"o":[],"k.E":"a"},"dg":{"a6":[],"k":["a"],"y":["a"],"L":["a"],"j":["a"],"a4":["a"],"i":["a"],"p":[],"f":["a"],"T":["a"],"o":[],"k.E":"a"},"dh":{"a6":[],"hM":[],"k":["a"],"y":["a"],"L":["a"],"j":["a"],"a4":["a"],"i":["a"],"p":[],"f":["a"],"T":["a"],"o":[],"k.E":"a"},"di":{"a6":[],"k":["a"],"y":["a"],"L":["a"],"j":["a"],"a4":["a"],"i":["a"],"p":[],"f":["a"],"T":["a"],"o":[],"k.E":"a"},"ca":{"a6":[],"k":["a"],"y":["a"],"L":["a"],"j":["a"],"a4":["a"],"i":["a"],"p":[],"f":["a"],"T":["a"],"o":[],"k.E":"a"},"bc":{"a6":[],"f1":[],"k":["a"],"y":["a"],"L":["a"],"j":["a"],"a4":["a"],"i":["a"],"p":[],"f":["a"],"T":["a"],"o":[],"k.E":"a"},"dM":{"q":[]},"bG":{"aE":[],"q":[]},"ad":{"q":[]},"cq":{"dI":["1"]},"F":{"ai":["1"]},"cG":{"j0":[]},"dV":{"cG":[],"j0":[]},"k":{"j":["1"],"i":["1"],"f":["1"]},"a_":{"ba":["1","2"]},"d_":{"bS":["h","j"]},"dy":{"bS":["h","j "]},"e4":{"t":["e4"]},"a3":{"t":["a3"]},"m":{"a2":[],"t":["a2"]},"aR":{"t":["aR"]},"a":{"a2":[],"t":["a2"]},"j":{"i":["1"],"f":["1"]},"a2":{"t":["a2"]},"h":{"t":["h"],"eI":[]},"z":{"e4":[],"t":["e4"]},"ct":{"kE":["1"]},"cO":{"q":[]},"aE":{"q":[]},"ah":{"q":[]},"aC":{"q":[]},"bZ":{"aC":[],"q":[]},"co":{"q":[]},"dv":{"q":[]},"be":{"q":[]},"cV":{"q":[]},"dk":{"q":[]},"cl":{"q":[]},"d2":{"q":[]},"e_":{"aW":[]},"dQ":{"l_":[]},"dL":{"e3":["bi"]},"dK":{"e3":["bD"]},"az":{"t":["az"]},"ap":{"t":["ap"]},"aj":{"t":["aj"]},"aq":{"t":["aq"]},"as":{"j":["e?"],"i":["e?"],"f":["e?"]},"cY":{"kz":[]},"dz":{"k":["e?"],"as":[],"j":["e?"],"i":["e?"],"f":["e?"],"k.E":"e?"},"bB":{"cU":[]},"dE":{"c_":[],"bs":[],"K":["N"]},"d1":{"H":[]},"dO":{"X":[]},"N":{"dx":["h","@"],"a_":["h","@"],"ba":["h","@"],"a_.K":"h","a_.V":"@"},"c_":{"bs":[],"K":["N"]},"dq":{"k":["N"],"dj":["N"],"j":["N"],"i":["N"],"bs":[],"f":["N"],"k.E":"N"},"dS":{"K":["N"]},"b7":{"l9":[]},"cR":{"H":[]},"cQ":{"X":[]},"au":{"cc":[]},"dC":{"l0":[]},"dA":{"l1":[]},"dD":{"l2":[]},"b_":{"aD":[]},"bC":{"k":["au"],"j":["au"],"i":["au"],"f":["au"],"k.E":"au"},"cg":{"H":[]},"dY":{"X":[]},"bf":{"aG":["a"],"k":["a"],"j":["a"],"i":["a"],"f":["a"],"k.E":"a","aG.E":"a"},"aG":{"k":["1"],"j":["1"],"i":["1"],"f":["1"]},"dP":{"aG":["a"],"k":["a"],"j":["a"],"i":["a"],"f":["a"]},"kK":{"y":["a"],"j":["a"],"i":["a"],"f":["a"]},"f1":{"y":["a"],"j":["a"],"i":["a"],"f":["a"]},"ld":{"y":["a"],"j":["a"],"i":["a"],"f":["a"]},"kI":{"y":["a"],"j":["a"],"i":["a"],"f":["a"]},"hM":{"y":["a"],"j":["a"],"i":["a"],"f":["a"]},"kJ":{"y":["a"],"j":["a"],"i":["a"],"f":["a"]},"lc":{"y":["a"],"j":["a"],"i":["a"],"f":["a"]},"kF":{"y":["m"],"j":["m"],"i":["m"],"f":["m"]},"kG":{"y":["m"],"j":["m"],"i":["m"],"f":["m"]}}'))
+A.lF(v.typeUniverse,JSON.parse('{"L":1,"cW":2}'))
+var u={c:"Error handler must accept one Object or one Object and a StackTrace as arguments, and return a value of the returned future's type"}
+var t=(function rtii(){var s=A.b2
+return{_:s("ao"),y:s("ao"),E:s("ao"),n:s("ad"),q:s("t<@>"),k:s("a3"),U:s("az"),J:s("aR"),O:s("i<@>"),Q:s("q"),Z:s("b6"),bM:s("f"),hf:s("f<@>"),Y:s("f"),D:s("r>"),f:s("r"),bb:s("r"),s:s("r"),eQ:s("r"),gn:s("r<@>"),c:s("r"),T:s("c1"),m:s("p"),C:s("U"),g:s("aB"),aU:s("a4<@>"),w:s("j"),dy:s("j"),b:s("j<@>"),L:s("j"),W:s("j"),A:s("ap"),B:s("aq"),t:s("aj"),a:s("by"),eB:s("a6"),bm:s("bc"),P:s("M"),K:s("e"),G:s("aC"),gT:s("nm"),bQ:s("+()"),cf:s("+(p?,p)"),u:s("+(e?,a)"),V:s("a7"),bJ:s("ce"),fI:s("N"),p:s("eQ"),h:s("cg"),l:s("aW"),N:s("h"),dm:s("o"),eK:s("aE"),I:s("f1"),ak:s("bg"),j:s("H"),r:s("X"),ab:s("dB"),gV:s("au"),cc:s("cp"),gB:s("bD"),cl:s("z"),al:s("dJ"),aW:s("bi"),d:s("F<@>"),cd:s("F<~>"),v:s("aO"),bO:s("aO(e)"),bB:s("aO(h)"),i:s("m"),z:s("@"),fO:s("@()"),x:s("@(e)"),R:s("@(e,aW)"),S:s("a"),ez:s("a()"),aa:s("a(h?,h?)"),f5:s("a(a)"),eH:s("ai?"),an:s("p?"),X:s("e?"),e:s("e?(as)"),dk:s("h?"),fN:s("bf?"),bx:s("H?"),F:s("bj<@,@>?"),fQ:s("aO?"),cD:s("m?"),h6:s("a?"),cg:s("a2?"),cN:s("~(aD,j)?"),ci:s("~(aD)?"),o:s("a2"),H:s("~"),M:s("~()"),bN:s("~(aD,j)"),fB:s("~(aD)"),hd:s("~(a,h,a)")}})();(function constants(){var s=hunkHelpers.makeConstList
+B.a8=J.d3.prototype
+B.b=J.r.prototype
+B.a=J.c0.prototype
+B.l=J.bv.prototype
+B.c=J.aS.prototype
+B.a9=J.aB.prototype
+B.aa=J.c2.prototype
+B.ae=A.c7.prototype
+B.e=A.bc.prototype
+B.A=J.dl.prototype
+B.n=J.bg.prototype
+B.o=new A.b5(1)
+B.B=new A.b5(2)
+B.j=new A.b5(3)
+B.C=new A.b5(4)
+B.aF=new A.b5(-1)
+B.m=new A.d2()
+B.p=function getTagFallback(o) {
+ var s = Object.prototype.toString.call(o);
+ return s.substring(8, s.length - 1);
+}
+B.D=function() {
+ var toStringFunction = Object.prototype.toString;
+ function getTag(o) {
+ var s = toStringFunction.call(o);
+ return s.substring(8, s.length - 1);
+ }
+ function getUnknownTag(object, tag) {
+ if (/^HTML[A-Z].*Element$/.test(tag)) {
+ var name = toStringFunction.call(object);
+ if (name == "[object Object]") return null;
+ return "HTMLElement";
+ }
+ }
+ function getUnknownTagGenericBrowser(object, tag) {
+ if (object instanceof HTMLElement) return "HTMLElement";
+ return getUnknownTag(object, tag);
+ }
+ function prototypeForTag(tag) {
+ if (typeof window == "undefined") return null;
+ if (typeof window[tag] == "undefined") return null;
+ var constructor = window[tag];
+ if (typeof constructor != "function") return null;
+ return constructor.prototype;
+ }
+ function discriminator(tag) { return null; }
+ var isBrowser = typeof HTMLElement == "function";
+ return {
+ getTag: getTag,
+ getUnknownTag: isBrowser ? getUnknownTagGenericBrowser : getUnknownTag,
+ prototypeForTag: prototypeForTag,
+ discriminator: discriminator };
+}
+B.I=function(getTagFallback) {
+ return function(hooks) {
+ if (typeof navigator != "object") return hooks;
+ var userAgent = navigator.userAgent;
+ if (typeof userAgent != "string") return hooks;
+ if (userAgent.indexOf("DumpRenderTree") >= 0) return hooks;
+ if (userAgent.indexOf("Chrome") >= 0) {
+ function confirm(p) {
+ return typeof window == "object" && window[p] && window[p].name == p;
+ }
+ if (confirm("Window") && confirm("HTMLElement")) return hooks;
+ }
+ hooks.getTag = getTagFallback;
+ };
+}
+B.E=function(hooks) {
+ if (typeof dartExperimentalFixupGetTag != "function") return hooks;
+ hooks.getTag = dartExperimentalFixupGetTag(hooks.getTag);
+}
+B.H=function(hooks) {
+ if (typeof navigator != "object") return hooks;
+ var userAgent = navigator.userAgent;
+ if (typeof userAgent != "string") return hooks;
+ if (userAgent.indexOf("Firefox") == -1) return hooks;
+ var getTag = hooks.getTag;
+ var quickMap = {
+ "BeforeUnloadEvent": "Event",
+ "DataTransfer": "Clipboard",
+ "GeoGeolocation": "Geolocation",
+ "Location": "!Location",
+ "WorkerMessageEvent": "MessageEvent",
+ "XMLDocument": "!Document"};
+ function getTagFirefox(o) {
+ var tag = getTag(o);
+ return quickMap[tag] || tag;
+ }
+ hooks.getTag = getTagFirefox;
+}
+B.G=function(hooks) {
+ if (typeof navigator != "object") return hooks;
+ var userAgent = navigator.userAgent;
+ if (typeof userAgent != "string") return hooks;
+ if (userAgent.indexOf("Trident/") == -1) return hooks;
+ var getTag = hooks.getTag;
+ var quickMap = {
+ "BeforeUnloadEvent": "Event",
+ "DataTransfer": "Clipboard",
+ "HTMLDDElement": "HTMLElement",
+ "HTMLDTElement": "HTMLElement",
+ "HTMLPhraseElement": "HTMLElement",
+ "Position": "Geoposition"
+ };
+ function getTagIE(o) {
+ var tag = getTag(o);
+ var newTag = quickMap[tag];
+ if (newTag) return newTag;
+ if (tag == "Object") {
+ if (window.DataView && (o instanceof window.DataView)) return "DataView";
+ }
+ return tag;
+ }
+ function prototypeForTagIE(tag) {
+ var constructor = window[tag];
+ if (constructor == null) return null;
+ return constructor.prototype;
+ }
+ hooks.getTag = getTagIE;
+ hooks.prototypeForTag = prototypeForTagIE;
+}
+B.F=function(hooks) {
+ var getTag = hooks.getTag;
+ var prototypeForTag = hooks.prototypeForTag;
+ function getTagFixed(o) {
+ var tag = getTag(o);
+ if (tag == "Document") {
+ if (!!o.xmlVersion) return "!Document";
+ return "!HTMLDocument";
+ }
+ return tag;
+ }
+ function prototypeForTagFixed(tag) {
+ if (tag == "Document") return null;
+ return prototypeForTag(tag);
+ }
+ hooks.getTag = getTagFixed;
+ hooks.prototypeForTag = prototypeForTagFixed;
+}
+B.q=function(hooks) { return hooks; }
+
+B.J=new A.dk()
+B.f=new A.eP()
+B.r=new A.dy()
+B.h=new A.f2()
+B.K=new A.dK()
+B.L=new A.dL()
+B.d=new A.dV()
+B.k=new A.e_()
+B.M=new A.aA(0,"exact")
+B.t=new A.aA(4,"halfAwayFromZero")
+B.R=new A.aR(0)
+B.u=new A.bu("/database",0,"database")
+B.v=new A.bu("/database-journal",1,"journal")
+B.S=new A.v("Invalid timestamp components.",null,null)
+B.T=new A.v("Invalid calendar date in instant.",null,null)
+B.U=new A.v("Expected a local date and time without a timezone.",null,null)
+B.V=new A.v("BC requires a positive era year.",null,null)
+B.W=new A.v("Decimal result requires rounding.",null,null)
+B.X=new A.v("Expected a finite decimal string.",null,null)
+B.Y=new A.v("Expected a Gregorian date without a timezone.",null,null)
+B.Z=new A.v("Expected a time without a timezone, with at most six fractional digits.",null,null)
+B.a_=new A.v("Expected a timestamp with at most six fractional digits.",null,null)
+B.a0=new A.v("Invalid UTC offset.",null,null)
+B.w=new A.v("Instant exceeds the common DateTime/PostgreSQL range.",null,null)
+B.a1=new A.v("Expected a local time or time text.",null,null)
+B.a2=new A.v("Decimal input is too long.",null,null)
+B.a3=new A.v("BC dates require a positive era year.",null,null)
+B.a4=new A.v("Expected a UTC instant or timestamp text.",null,null)
+B.a5=new A.v("Expected a local timestamp or timestamp text.",null,null)
+B.a6=new A.v("Decimal exponent is out of range.",null,null)
+B.a7=new A.v("Exact decimal storage requires text or an integer.",null,null)
+B.N=new A.aA(1,"towardZero")
+B.O=new A.aA(2,"floor")
+B.P=new A.aA(3,"ceiling")
+B.Q=new A.aA(5,"halfEven")
+B.i=s([B.M,B.N,B.O,B.P,B.t,B.Q],A.b2("r"))
+B.x=s([1e6,1e5,1e4,1000,100,10,1],A.b2("r"))
+B.ab=s([],t.D)
+B.ac=s([],t.s)
+B.y=s([],t.c)
+B.ad=s([B.u,B.v],A.b2("r"))
+B.af={}
+B.z=new A.bU(B.af,[],A.b2("bU"))
+B.aG=new A.eH(2,"readWriteCreate")
+B.ag=new A.a0("DRIVER.OPEN","Worker is already open.")
+B.ah=new A.a0("CURSOR.READ_ONLY","Streaming requires a read-only query.")
+B.ai=new A.a0("CODEC.INTEGER","Browser int transport requires a safe integer; use BigInt for wider integers or SqlReal for floating values.")
+B.aj=new A.a0("DRIVER.PROTOCOL","Invalid SQLite worker value.")
+B.ak=new A.a0("CODEC.PARAMETER","Unsupported SQLite wire value.")
+B.al=new A.a0("DRIVER.STORAGE","Unknown browser storage.")
+B.am=new A.a0("DRIVER.CLOSED","SQLite worker is not open.")
+B.an=new A.a0("DRIVER.FOREIGN_KEYS","SQLite foreign keys could not be enabled.")
+B.ao=new A.a0("CURSOR.CLOSED","Cursor has ended.")
+B.ap=new A.a0("DRIVER.PROTOCOL","Unknown SQLite worker command.")
+B.aq=A.an("nb")
+B.ar=A.an("ir")
+B.as=A.an("kF")
+B.at=A.an("kG")
+B.au=A.an("kI")
+B.av=A.an("kJ")
+B.aw=A.an("kK")
+B.ax=A.an("e")
+B.ay=A.an("hM")
+B.az=A.an("lc")
+B.aA=A.an("ld")
+B.aB=A.an("f1")
+B.aC=new A.aZ(14)
+B.aD=new A.aZ(522)
+B.aE=new A.aZ(778)})();(function staticFields(){$.fz=null
+$.a9=A.x([],t.f)
+$.iR=null
+$.ip=null
+$.io=null
+$.jH=null
+$.jD=null
+$.jL=null
+$.hb=null
+$.hi=null
+$.i8=null
+$.fC=A.x([],A.b2("r?>"))
+$.bK=null
+$.cJ=null
+$.cK=null
+$.i2=!1
+$.w=B.d
+$.j3=null
+$.j4=null
+$.j5=null
+$.j6=null
+$.hP=A.fl("_lastQuoRemDigits")
+$.hQ=A.fl("_lastQuoRemUsed")
+$.cs=A.fl("_lastRemUsed")
+$.hR=A.fl("_lastRem_nsh")})();(function lazyInitializers(){var s=hunkHelpers.lazyFinal,r=hunkHelpers.lazy
+s($,"nd","jX",()=>A.hc("_$dart_dartClosure"))
+s($,"nc","bQ",()=>A.hc("_$dart_dartClosure_dartJSInterop"))
+s($,"nN","kj",()=>A.x([new J.d4()],A.b2("r")))
+s($,"no","k2",()=>A.aF(A.f0({
+toString:function(){return"$receiver$"}})))
+s($,"np","k3",()=>A.aF(A.f0({$method$:null,
+toString:function(){return"$receiver$"}})))
+s($,"nq","k4",()=>A.aF(A.f0(null)))
+s($,"nr","k5",()=>A.aF(function(){var $argumentsExpr$="$arguments$"
+try{null.$method$($argumentsExpr$)}catch(q){return q.message}}()))
+s($,"nu","k8",()=>A.aF(A.f0(void 0)))
+s($,"nv","k9",()=>A.aF(function(){var $argumentsExpr$="$arguments$"
+try{(void 0).$method$($argumentsExpr$)}catch(q){return q.message}}()))
+s($,"nt","k7",()=>A.aF(A.iY(null)))
+s($,"ns","k6",()=>A.aF(function(){try{null.$method$}catch(q){return q.message}}()))
+s($,"nx","kb",()=>A.aF(A.iY(void 0)))
+s($,"nw","ka",()=>A.aF(function(){try{(void 0).$method$}catch(q){return q.message}}()))
+s($,"nz","id",()=>A.lf())
+s($,"nK","kh",()=>A.iP(4096))
+s($,"nI","kf",()=>new A.fL().$0())
+s($,"nJ","kg",()=>new A.fK().$0())
+s($,"nG","E",()=>A.cr(0))
+s($,"nE","Z",()=>A.cr(1))
+s($,"nF","ih",()=>A.cr(2))
+s($,"nC","ig",()=>$.Z().D(0))
+s($,"nA","ie",()=>A.cr(1e4))
+r($,"nD","kd",()=>A.cd("^\\s*([+-]?)((0x[a-f0-9]+)|(\\d+)|([a-z0-9]+))\\s*$",!1))
+s($,"nB","kc",()=>A.iP(8))
+s($,"nH","ke",()=>typeof FinalizationRegistry=="function"?FinalizationRegistry:null)
+s($,"nL","hu",()=>A.jJ(B.ax))
+s($,"nl","k1",()=>{var q=new A.dQ(new DataView(new ArrayBuffer(A.lW(8))))
+q.ca()
+return q})
+s($,"nf","ib",()=>A.kB($.E(),0))
+s($,"ne","jY",()=>A.cd("^([+-]?)([0-9]*)(?:\\.([0-9]*))?(?:[eE]([+-]?[0-9]+))?$",!0))
+s($,"nM","ki",()=>A.cd("^(-?\\d{4,7})-(\\d{2})-(\\d{2})[ T](\\d{2}:\\d{2}(?::\\d{2}(?:\\.\\d{1,6})?)?)(Z|[+-]\\d{2}(?::?\\d{2})?(?::?\\d{2})?)?( BC)?$",!1))
+s($,"ni","k_",()=>A.cd("^(-?\\d{4,7})-(\\d{2})-(\\d{2})( BC)?$",!1))
+s($,"nj","k0",()=>A.cd("^(\\d{2}):(\\d{2})(?::(\\d{2})(?:\\.(\\d{1,6}))?)?$",!0))
+s($,"nh","jZ",()=>A.cd("^(-?\\d{4,7}-\\d{2}-\\d{2})[ T](\\d{2}:\\d{2}(?::\\d{2}(?:\\.\\d{1,6})?)?)( BC)?$",!1))
+s($,"na","jW",()=>$.Z().O(0,63).D(0))
+s($,"n9","jV",()=>{var q=$.Z()
+return q.O(0,63).ac(0,q)})
+s($,"n8","hs",()=>$.k1())
+s($,"ny","ic",()=>new A.d0(new WeakMap(),A.b2("d0")))
+s($,"ng","ht",()=>{var q,p,o=A.d9(t.N,A.b2("bu"))
+for(q=0;q<2;++q){p=B.ad[q]
+o.A(0,p.c,p)}return o})})();(function nativeSupport(){!function(){var s=function(a){var m={}
+m[a]=1
+return Object.keys(hunkHelpers.convertToFastObject(m))[0]}
+v.getIsolateTag=function(a){return s("___dart_"+a+v.isolateTag)}
+var r="___dart_isolate_tags_"
+var q=Object[r]||(Object[r]=Object.create(null))
+var p="_ZxYxX"
+for(var o=0;;o++){var n=s(p+"_"+o+"_")
+if(!(n in q)){q[n]=1
+v.isolateTag=n
+break}}v.dispatchPropertyName=v.getIsolateTag("dispatch_record")}()
+hunkHelpers.setOrUpdateInterceptorsByTag({SharedArrayBuffer:A.aU,ArrayBuffer:A.by,ArrayBufferView:A.c9,DataView:A.c7,Float32Array:A.dc,Float64Array:A.dd,Int16Array:A.de,Int32Array:A.df,Int8Array:A.dg,Uint16Array:A.dh,Uint32Array:A.di,Uint8ClampedArray:A.ca,CanvasPixelArray:A.ca,Uint8Array:A.bc})
+hunkHelpers.setOrUpdateLeafTags({SharedArrayBuffer:true,ArrayBuffer:true,ArrayBufferView:false,DataView:true,Float32Array:true,Float64Array:true,Int16Array:true,Int32Array:true,Int8Array:true,Uint16Array:true,Uint32Array:true,Uint8ClampedArray:true,CanvasPixelArray:true,Uint8Array:false})
+A.L.$nativeSuperclassTag="ArrayBufferView"
+A.cu.$nativeSuperclassTag="ArrayBufferView"
+A.cv.$nativeSuperclassTag="ArrayBufferView"
+A.c8.$nativeSuperclassTag="ArrayBufferView"
+A.cw.$nativeSuperclassTag="ArrayBufferView"
+A.cx.$nativeSuperclassTag="ArrayBufferView"
+A.a6.$nativeSuperclassTag="ArrayBufferView"})()
+Function.prototype.$1=function(a){return this(a)}
+Function.prototype.$2=function(a,b){return this(a,b)}
+Function.prototype.$0=function(){return this()}
+Function.prototype.$1$1=function(a){return this(a)}
+Function.prototype.$3=function(a,b,c){return this(a,b,c)}
+Function.prototype.$4=function(a,b,c,d){return this(a,b,c,d)}
+Function.prototype.$1$2=function(a,b){return this(a,b)}
+Function.prototype.$5=function(a,b,c,d,e){return this(a,b,c,d,e)}
+convertAllToFastObject(w)
+convertToFastObject($);(function(a){if(typeof document==="undefined"){a(null)
+return}if(typeof document.currentScript!="undefined"){a(document.currentScript)
+return}var s=document.scripts
+function onLoad(b){for(var q=0;q main(List arguments) => runOrmCli(arguments);
diff --git a/build.yaml b/build.yaml
new file mode 100644
index 00000000..2edf7c54
--- /dev/null
+++ b/build.yaml
@@ -0,0 +1,15 @@
+builders:
+ orm:
+ import: "package:orm/builder.dart"
+ builder_factories: ["ormBuilder"]
+ build_extensions:
+ ".dart": [".orm.dart", ".orm.json"]
+ auto_apply: none
+ build_to: source
+ queries:
+ import: "package:orm/builder.dart"
+ builder_factories: ["ormQueryBuilder"]
+ build_extensions:
+ ".dart": [".queries.dart", ".queries.json"]
+ auto_apply: none
+ build_to: source
diff --git a/dart_test.yaml b/dart_test.yaml
new file mode 100644
index 00000000..e4c737d2
--- /dev/null
+++ b/dart_test.yaml
@@ -0,0 +1,7 @@
+# These suites launch Dart CLI processes in the same package. On macOS the SDK
+# rewrites/codesigns one shared SQLite native-asset file during their startup.
+# Serialize suites there; explicit concurrent database operations inside tests
+# still run concurrently.
+on_os:
+ mac-os:
+ concurrency: 1
diff --git a/docs/acceptance.md b/docs/acceptance.md
new file mode 100644
index 00000000..eadf3f8b
--- /dev/null
+++ b/docs/acceptance.md
@@ -0,0 +1,116 @@
+# Design acceptance map
+
+The current redesign adds independently usable modules, nominal model results,
+typed project configuration and MySQL/MariaDB support. Its current acceptance state
+is recorded in [the final local acceptance](../research/validation/standalone-redesign.md)
+and [progress](progress.md); engine-specific limitations are in
+[capabilities](capabilities.md). The table below also preserves earlier evidence
+for unchanged feature families.
+
+The earlier [API/correctness audit](../research/api-correctness-audit.md) passes
+872 native tests and 20 real Chrome checks for each of JavaScript and Dart WASM.
+[Its validation record](../research/validation/api-audit.md) pins the runtime source
+and preserves platform/performance limits. The [API guide](api.md) documents the
+reviewed import, selection, execution and history boundaries.
+
+The common ORM lifecycle in
+[`new-dart-orm-design.md`](../research/new-dart-orm-design.md) is implemented and
+accepted within the [reviewed capability boundaries](capabilities.md). The original
+native baseline passed 835 tests with both databases enabled; the documented usage
+run and static analysis also passed. This map identifies the checked scenarios
+and separately captured platforms, rather than certifying every database feature
+or deployment target. Historical measurements remain pinned to their source.
+
+## Implementation with direct test coverage
+
+| Design requirement | Current evidence |
+| --- | --- |
+| §§2, 4–5: nominal class and Record declarations, separate table identity, restricted selectors, static input/result types | `lib/schema.dart`, `lib/src/generate/`; `generator_test`, `types_test`, `nominal_generation_test`, `nominal_database_test`, generated fixtures and `generated_database_test` |
+| Standalone driver, runtime, metadata and typed SQL libraries | `layer_boundaries_test`, `runtime_test`, `runtime_lifecycle_review_test`, `sql_builder_test`; offline generated queries and independent raw sessions |
+| MySQL/MariaDB typed writes, values, sessions, import and migration recovery | `mysql_driver_test`, `mysql_database_test`, `mysql_import_test`, `mysql_transaction_boundary_test`, `mysql_migration_test`; both engines run against separate real servers |
+| Typed project CLI and four-engine generation | `cli_workflow_test`, `generator_dialects_test`; offline initialization, current-source regeneration and reviewed Dart migration lifecycle |
+| §§4–5: compound keys, physical names, indexes, FK navigation, domain codecs | Generator, `relation_test`, `integer_test`, `custom_codec_test`, catalog/import tests |
+| §§5, 10–11: temporal column precision | `temporal_precision_test`: generated declarations and SQL coercion, epoch ties, finite ranges, defaults/computed values, rounded relation keys, import/catalog drift and reviewed migration rollback; real JS/WASM worker scenario; [semantics](types.md#temporal-precision) |
+| §4.2: explicit navigation without database FKs | `relatesTo`; `unconstrained_relation_test` checks missing/duplicate targets, composite/self/inverse edges, no FK/index/cascade, watch and constraint transitions; generator/type negatives |
+| §12 declaration table: general CHECK constraints | `check_test`, generator/CLI tests and browser scenario: declaration, native enforcement/NULL, catalog/import, drift, add/change/remove/rename and atomic rollback; limits in [checks](checks.md) |
+| §§4.3, 5, 8: client-generated values separate from database defaults | `client_default_test`, generator/type negatives and browser scenario: typed factories, omission/value/null/DEFAULT, batches, conflicts, preparation/reuse and rollback; snapshots/imports exclude client code; [defaults](defaults.md) |
+| §§4.3, 5, 8: database computed/read-only columns | `computed_test`, generator/type negatives, CLI and browser scenario: stored/virtual declaration, read-only fields, CRUD/relations, catalog/import, expression/type/add/drop/materialization/rename and atomic rollback; [native limits](computed.md) |
+| §6: scalar, positional/named Record and DTO projections; dynamic fields and lazy immutable queries | `database_test`, `generated_database_test`, `union_test`; mappings execute after rows arrive |
+| §6: joins, grouping/HAVING, subqueries, CTEs, windows and UNION | `union_test`, `relation_test`, `watch_test`, decimal/temporal query suites; exported-column and scope checks |
+| §6: named SQL with typed parameters/results and database structure checking | `named_sql_test`, `named_sql_generation_test`, real CLI/build_runner workflows |
+| §§6–7: stable cursors, optional/required to-one, batched lists and per-parent limits | `database_test`, `relation_test`, cursor checks in numeric/temporal suites; actual query counts and nullable presence |
+| §§4.2, 7, 12: many-to-many business records | `example/teams`, `many_to_many_test`, generated-type negatives and browser scenario: two FKs, composite membership keys, role/time payloads, bidirectional and nested projections, per-parent limits, parameter chunks, transaction/upsert/cascade/watch and actual query/row counts; [usage](relations.md#many-to-many-with-business-fields) |
+| §8: create/patch/delete, absent versus NULL/default, atomic expression writes, batch/upsert/returning | Generated client and `database_test`; later-chunk failure rolls back earlier chunks |
+| §9: explicit sessions, savepoints, lifetime, cancellation, unknown commits, retries and acquisition limits | `transaction_test`, `retry_test`, `acquisition_test`, `stream_test`; real database interruption and state readback |
+| §10: reviewed snapshots/diffs, explicit rename/conversion, history, baseline/drift and recoverable migrations | `migration_test`, `migration_target_test`, `migration_recovery_test`, `backfill_test`, `schema_version_test`, import and CLI suites |
+| §11: distinct PostgreSQL/native SQLite configuration and connection ownership | `lib/postgres.dart`, `lib/sqlite.dart`; native suites exercise both backends, capability rejection, borrowed pools and disposal |
+| §§11–12: worker/persistence, real cursor streaming and commit-driven observation | Native `stream_test`/`watch_test`; real JS and Dart WASM browser reports include OPFS reload recovery and upgrade |
+| §§11–12: native Flutter | `example/flutter`, `tool/test_flutter.dart` and [Android capture](flutter.md): version 1 debug APK → version 2 AOT release APK → independent process restart; 4/17/11 assertions cover background SQLite, persistence, live migration/catalog, generated CRUD/relations, rollback/watch and cancellation/reuse |
+| §12: inspectable query structure and execution phases | `plan_test`, `observation_test` and real JS/WASM teams scenario: non-executing SQL/column/key/join/batch descriptions, composite parameter capacity, real acquisition waits/cancellation, decode/stream/RETURNING scopes and observer exception isolation; [measurement limits](observability.md) |
+| §13.3: runtime cost comparison | `tool/benchmark_runtime.dart`, captured `research/benchmarks/runtime.json` and [method/results](performance.md): same Driver/SQL/parameters/shape, four read workloads, 200 samples per lane, concurrent throughput, byte/row counts, acquisition distributions, live heap and selected allocation traces; native JIT with actual echo calibration of controlled TCP latency, not a remote deployment or total-allocation-byte census |
+| §13.3: editor protocol measurements | `tool/benchmark_editor.dart`, `research/benchmarks/editor.json` and [method/results](generation.md#editor-completion-diagnostics-and-rename): real generated APIs at 10/100/1000 models, 300 warm samples across five completion probes, twelve exact-code/range diagnostic checks, language-symbol rename edits and final consumer analysis; the subsequent `research/validation/editor-recovery.json` records a same-session timeout at ten models and a successful restart path, without claiming GUI or general IDE reliability |
+| §13.2: declaration-form experiment | `tool/compare_authoring.dart`, `research/benchmarks/authoring.json` and [scope/results](authoring.md): actual Record/primary-class/table inputs for User/Post/Profile/Follow, identical canonical schema/client/snapshot for base/type-edit/rename variants, six stale-consumer failures and repaired analyses, complex constraints, schema LSP edits and fourteen original-source error locations; experimental class/table adapters emit Record rows and do not implement nominal object materialization |
+
+The filenames in this table refer to `test/.dart` unless another location
+is shown. The browser report is
+[`research/validation/browser.json`](../research/validation/browser.json), with
+commands and limits in [SQLite web](sqlite-web.md).
+
+The subsequent [selection cost capture](../research/benchmarks/runtime-selection.json)
+uses runtime `d0a8c9a`. Exact SQL, parameters and result/transport volumes match the
+baseline. It records fewer selected List allocations, without establishing a
+latency or throughput gain; the [comparison](performance.md#direct-selection-decoding)
+also documents the PostgreSQL protocol lifecycle tradeoff. `selection_test` adds
+direct coverage for deferred/ordered mapping, repeated fields, all typed arities,
+streaming, failures and dynamic field snapshots on both native backends.
+
+## Final lifecycle audit
+
+| Design §3 scenario / acceptance gate | Verification |
+| --- | --- |
+| Add a defaulted field without rewriting existing create calls | Generated type/default tests and actual Android v1 → v2 migration preserve rows and populate the new field |
+| Select emails only, returning `List` | Native projection/plan tests and executable cookbook scalar selection |
+| Root pagination plus each parent's latest three titles | Native relation checks, `three_posts` runtime workload and browser generated-relation scenario; actual SQL counts and parameter chunks |
+| Create a parent and children in one transaction | README and teams examples, native generated tests and actual Android relation write |
+| Clear a nullable field and increment atomically | Generated patch/expression-write tests, NULL/default negative type checks and transaction suites |
+| Separate Dart rename from physical column rename | Generated snapshot/authoring tests, CLI migration diff and real migration/recovery tests; Record field rename remains manual |
+| Switch SQLite memory/file/worker storage | Native persistence and read-only tests, Chrome JS/WASM OPFS reload/upgrade, Android APK upgrade/restart |
+| Keep database-specific configuration and ownership explicit | Separate typed driver inputs, wrong-backend compilation failures, borrowed PostgreSQL pools and cancellation/acquisition tests; unimplemented transports are not certified |
+| Process large results and release sessions | Real SQLite/PostgreSQL cursors, batching, early stream cancellation and post-failure connection reuse; browser stream/release scenario |
+| Check version, migration state and live structure before deployment | CLI/import/baseline tests, application-version tests, durable backfill and nontransactional recovery, Android bundled migration checks |
+| Review query, type and unmanaged catalog coverage | [Capability review](capabilities.md); final native suite includes real triggers and complete policy/RLS metadata checks |
+| Run documented onboarding and complex query usage | [Usage capture](../research/validation/usage.json): dependencies, generation, both existing examples, nine cookbook checks on each backend, migration-chain validation and clean analysis |
+
+The [single-engine migration correction](../research/validation/migration-targets.md)
+records a full run with 845 passes and two incorrectly configured crash-test
+registries, then 21 passing target/recovery tests after correcting them. It also
+verifies native AOT bundles, real Chrome JS/WASM and the public CLI workflow.
+Each history now fixes one engine, selected expressions alone affect fingerprints,
+and wrong connections fail before migration SQL. Android runtime was
+not rerun for that correction; its earlier capture remains tied to its original revision.
+
+The [Dart migration acceptance](../research/validation/dart-migrations.json) records
+the replacement of JSON artifacts with Dart snapshots, fixed history and static
+registration. Its full native run passed 837 tests and found one old fixture path;
+the correction and final generator changes pass a 76-test follow-up. The record
+retains both logs instead of claiming a single all-green full invocation. AOT
+checks execute compiled history without consumer source files and resume historical
+backfills. The original [835-test capture](../research/validation/native.json)
+remains a historical baseline.
+
+The earlier Chrome JS/WASM and Android APK captures use the original Dart workflow source.
+Android proves the native Flutter lane on its recorded emulator, including compiled
+migration definitions, upgrade and process restart; it does not certify Apple
+platforms or every server type/scenario. See [Flutter scope](flutter.md) and
+[browser scope](sqlite-web.md) for the exact assertions.
+
+## Extension boundaries in the design
+
+Design §12 explicitly places PostgreSQL-specific JSON/array/COPY/locking and
+SQLite FTS expansion behind real demand. HTTP/serverless transports require
+their own session/capability verification. These are not silently provided by a
+native driver or raw-SQL escape hatch. Distributed transactions, synchronization,
+arbitrary object-graph tracking and a general optimizer remain separately scoped
+in the design. Calendar SQL arithmetic, timezone-rule conversion and additional
+native types also remain explicit extensions, as recorded in the capability
+review. They are not presented as working APIs or hidden behind silent fallbacks.
diff --git a/docs/api.md b/docs/api.md
new file mode 100644
index 00000000..eb61af1d
--- /dev/null
+++ b/docs/api.md
@@ -0,0 +1,155 @@
+# API and mental model
+
+Start with an immutable Dart class, generate its client, choose a database entrypoint,
+and use the generated table getters. Each query belongs to that database view.
+Migrations have a separate, fixed history for the chosen engine.
+
+## Imports
+
+SQLite uses `sqlite.dart` on native platforms and the web. `SqliteOptions.memory()`
+is portable. `persistent(name, nativePath: ...)` uses the native path or the named
+browser database. Flutter bundles its browser resources automatically; see
+[SQLite Web setup](sqlite-web.md). Platform transports are internal.
+
+| Module or use | Import | Purpose |
+| --- | --- | --- |
+| Values | `package:orm/values.dart` | Codecs, decimal/temporal/domain value contracts |
+| Driver contracts | `package:orm/driver.dart` | SQL commands, raw results, connections and capabilities |
+| Database adapters | `package:orm/drivers/sqlite.dart`, `postgres.dart`, `mysql.dart`, `mariadb.dart` under `drivers/` | Raw drivers without ORM models |
+| Raw SQL execution | `package:orm/runtime.dart` | `SqlDatabase`, sessions, transactions, cursors and observations |
+| Physical schema | `package:orm/schema_model.dart` | Columns, keys, constraints and indexes without execution |
+| Typed SQL | `package:orm/sql.dart` | Query construction, typed projections and `SqlBuilder` without a connection runtime |
+| ORM execution | `package:orm/orm.dart` | `Database` binds typed queries to `SqlDatabase` and adds subscriptions |
+| Schema declaration | `package:orm/schema.dart` | Model annotations, entities, keys and relations |
+| Application convenience | Generated `schema.orm.dart` plus `package:orm/sqlite.dart`, `postgres.dart`, `mysql.dart` or `mariadb.dart` | Model types, table getters and the chosen adapter |
+| Migration or snapshot | `package:orm/migrate.dart` | Physical history, steps, checksums and execution against `SqlDatabase` |
+| Project CLI | `package:orm/cli.dart` | `OrmConfig`, static history and unified project commands |
+| Migration-only executable | `package:orm/migrate_cli.dart` | Programmatic commands with a static history and raw connection factory |
+| Generation scripts | `package:orm/generate.dart` | Analyze declarations and write derived Dart files |
+| build_runner configuration | `package:orm/builder.dart` | Builder factories only |
+
+Generated clients export their declared model classes (or explicit Record aliases), but not `entity()` declaration
+values or unrelated application helpers. Types used inside rows, such as a custom
+ID or enum, remain owned by their defining library. Import that library when
+constructing those values. Use import prefixes for multiple generated clients.
+
+These are real dependency boundaries within one package. `sql.dart` does not
+import the connection runtime or ORM, and `runtime.dart` does not import the
+query builder. `migrate.dart` uses raw sessions and physical metadata without
+model declarations or generated query code. None of these runtime/schema imports
+pull in the analyzer, build system or a concrete database adapter. `sqlite.dart`
+selects its platform implementation; each server engine has its own options.
+The single package still declares tooling dependencies for its CLI and builders;
+`pub get` resolves them. This import boundary avoids runtime initialization and
+compilation dependencies, not the dependency-download cost of one package.
+
+For raw SQL, construct `SqlDatabase(await SqliteDriver.open(options))` from
+`runtime.dart` and `drivers/sqlite.dart`. Add typed execution later with
+`Database.fromSql(raw)`; it uses the same runtime rather than another pool.
+`db.sql` exposes that runtime to migrations and catalog operations.
+
+For offline compilation, import `sql.dart` and a generated client:
+
+```dart
+final command = SqlBuilder(SqlDialect.postgres)
+ .users.where((u) => u.email.eq('seven@example.com'))
+ .select((u) => u.id)
+ .compile();
+// command.sql and separately bound command.parameters; no connection opened.
+```
+
+Executing an unbound builder fails with `QUERY.UNBOUND`. Generated table getters
+and named SQL bindings target `QueryContext`, which both `SqlBuilder` and the ORM
+implement. Field and result types remain static; SQL capabilities and a missing
+named-query engine variant are checked against the chosen context before I/O.
+
+## Three kinds of Dart files
+
+`schema.dart` is the current declaration. `schema.orm.dart` and
+`schema.snapshot.dart` are reproducible outputs; regenerate them after editing the
+declaration. `migrations/m0001_*.dart` is reviewed history. It contains its own frozen
+physical schema and fixed fingerprint, independent of the latest models.
+
+Generation validates the structure and types. A migration history selects SQLite,
+PostgreSQL, MySQL or MariaDB and validates that engine's capabilities. A SQLite-only declaration
+may use a virtual indexed column; PostgreSQL restrictions should not prevent its
+generation. The selected engine still rejects unsupported DDL before applying it.
+Changing a connection URL does not convert a migration history.
+
+## Shape, identity and selection
+
+The declared class is the complete row type. A `User` and an unrelated class with
+identical fields remain different Dart types. Record projections remain
+structural. Two tables can use the same class or Record shape while remaining
+distinct SQL sources. `table.alias()` creates a new occurrence for joins
+and self joins. Capturing a field from an unrelated query is a scope error.
+
+`select((u) => u.email)` returns `List` from `get()`. `.row` composes SQL
+expressions into a positional Record; `.map(...)` shapes decoded values into a
+named Record or DTO. A Dart mapper does not become a SQL expression. Runtime
+`fields({...})` selection deliberately returns `Map`.
+
+`alias.optional(selection)` checks that alias's presence. It does not prove another
+left-joined alias exists. Give each optional alias its own guard, or use nullable
+expressions. Relationships follow the same rule: `one()` can be absent, `required()`
+checks presence, and `many()` loads a collection. [Relationship execution](relations.md)
+documents joins, batched queries and consistency boundaries.
+
+## Preparing and executing
+
+`where`, `select`, `orderBy`, `take`, `skip` and `map` return new descriptions.
+Repeated `where` adds predicates; `orderBy`, `take` and `skip` replace their own
+settings. `compile()`/`inspect()` perform no I/O. `get()`/`first()`/`single()` execute
+reads; a stream acquires a cursor when listened to.
+
+Generated `create(...)` and `patch(...)` execute immediately. `insert(...)`,
+`insertMany(...)`, `update(...)` and `delete()` prepare mutations; call `execute()`
+or `returning(...).get()`. Prepared inserts evaluate client defaults once when
+constructed. Re-executing the prepared insert reuses those values.
+
+`Change.keep()` omits an assignment, `.set(null)` writes SQL NULL to a nullable
+field, and `.defaultValue()` requests the database default. An empty update is an
+error. `RETURNING` returns scalar SQL projections; query relationships afterward.
+For statement deadlines or cancellation, use the prepared mutation's execution
+options. [Defaults](defaults.md) and [execution](execution.md) specify the limits.
+
+## Connection and transaction ownership
+
+The root `SqlDatabase` owns its driver; `Database` uses that runtime. `session` borrows one connection; `transaction`
+borrows one connection and commits or rolls back the callback's writes. Only use
+the callback's `tx` to construct that transaction's queries. Subqueries, CTEs and
+UNION operands must all use the same view. Use `savepoint` for a recoverable nested
+unit; borrowed views expire at callback completion.
+
+Pass `tx` into helper functions. Calling the captured root `db` separately inside
+the callback requests separate work: a pool may run it outside the transaction,
+and a single-connection SQLite driver may wait on the callback's own lease.
+Composition checks reject mixed query descriptions; they do not rewrite unrelated
+root calls into transaction calls.
+
+```dart
+await db.transaction((tx) async {
+ final user = await tx.users.create(email: 'seven@example.com');
+ await tx.posts.create(
+ authorId: user.id,
+ title: 'First post',
+ createdAt: DateTime.now(),
+ );
+});
+```
+
+Await every operation before returning from the callback. Batch inserts use one
+transaction across chunks. A normal query with batched relationships reuses its
+connection but does not automatically create a snapshot transaction. Choose an
+appropriate explicit transaction when a consistent multi-query snapshot matters.
+Query observations expose actual SQL and transaction statements.
+
+Raw SQL remains explicit: bind values in `SqlCommand` or typed `sql` expressions,
+declare affected/read tables for subscriptions, and use reviewed migration steps
+for schema changes. The ORM does not infer an object graph, external writes,
+automatic transaction replay or destructive renames.
+
+Custom codecs, manual Table definitions and Driver implementations are explicit
+extension contracts. Their authors supply the correct storage mapping and native
+behavior. Dart types cannot prove that a live external schema still matches those
+definitions; use catalog verification when that boundary matters.
diff --git a/docs/authoring.md b/docs/authoring.md
new file mode 100644
index 00000000..9b9810b0
--- /dev/null
+++ b/docs/authoring.md
@@ -0,0 +1,173 @@
+# Models and typed queries
+
+Declare an immutable Dart class once. The generated client returns instances of
+that class, including from inserts and relationships. It does not generate a
+second row type or convert the class into a Record.
+
+```dart
+import 'package:orm/schema.dart';
+
+final class User({
+ @Id.generated() required final int id,
+ @Unique() required final String email,
+ required final String? nickname,
+ @Default.sql('false') required final bool active,
+});
+
+final class Post(
+ @Id.generated() final int id,
+ final int authorId,
+ final String title,
+);
+
+final users = entity(table: 'users');
+final posts = entity(table: 'posts');
+final author = posts
+ .key((p) => p.authorId)
+ .references(users.key((u) => u.id), inverse: 'posts', onDelete: .cascade);
+```
+
+Primary constructors require Dart 3.13. They declare fields and constructor
+parameters together; they are ordinary Dart classes with ordinary nominal type
+identity. See the [Dart language documentation](https://dart.dev/language/primary-constructors).
+
+`entity()` gives the table its own identity and physical name. Two tables
+can use the same row class, and a self-join still has separate table occurrences.
+Row identity does not determine SQL scope.
+
+Generate with `dart run orm generate lib/schema.dart`, then import the generated
+client and the chosen driver. [Generation](generation.md) describes standalone
+and build_runner workflows. New projects can start with `dart run orm init
+--database sqlite`; after initialization, `dart run orm generate` reads the typed
+project configuration.
+
+```dart
+final User user = await db.users.create(email: 'seven@example.com');
+await db.users.byId(user.id).patch(nickname: .set('Seven'));
+await db.users.byId(user.id).patch(nickname: .set(null));
+
+final List active = await db.users
+ .where((u) => u.active.eq(true))
+ .get();
+
+final List posts = await db.users
+ .byId(user.id)
+ .select((u) => u.posts.many())
+ .single();
+```
+
+The same field declarations determine constructor values, typed query fields,
+create parameters, patch parameters, codecs and the physical schema. Application
+code does not repeat column types in a table class or a generated row interface.
+The generated client imports `sql.dart` and binds to `QueryContext`. It can be used
+with an offline `SqlBuilder` as well as a connected ORM `Database`; the model
+declaration itself only depends on the schema/value layer.
+
+## Full rows, writes and projections
+
+The model constructor represents a complete database row. Every constructor
+parameter is required, including nullable columns and generated IDs. `User.id`
+stays `int`: creating a user does not require weakening the stored row to `int?`.
+
+The generated `create` method has its own insert contract:
+
+- Ordinary non-null columns are required.
+- Nullable columns without defaults can be omitted and are inserted as NULL.
+- Generated values, SQL defaults and client defaults use `Change` with
+ `.keep()` as the default. `.set(value)` explicitly supplies a value.
+- Computed columns are absent from writes.
+
+Patch parameters use `Change` to distinguish omission from explicit NULL.
+`patch()` keeps an omitted field; `patch(nickname: .set(null))` clears it.
+Generated identities and computed columns are absent from patch parameters.
+
+Use `@Default.sql` for database defaults and `@ClientDefault(factory)` for Dart
+insert defaults. Constructor defaults are rejected: they would otherwise suggest
+an insert behavior that the database does not implement. Neither constructors nor
+client factories run during generation. Client factories run when building the
+insert; the model constructor runs when decoding the resulting row.
+
+Selected shapes remain independent of complete models. Project a scalar, a typed
+Record, or a separate application DTO:
+
+```dart
+final cards = await db.users.select((u) => (
+ u.id,
+ u.email,
+ u.posts.take(3).select((p) => p.title).many(),
+).map((id, email, posts) => (id: id, email: email, posts: posts))).get();
+// List<({int id, String email, List posts})>
+```
+
+Selecting two columns does not produce a partly populated `User`. Relationships
+are explicit query selections; they do not add hidden lazy-loading properties or
+queries to the row class. A foreign key remains a separate typed declaration,
+including for composite keys and multiple edges to the same table.
+
+## Supported declarations and errors
+
+Generated entity classes must be public, final, non-generic classes declared in
+the selected schema file. Their unnamed primary constructor accepts public,
+explicitly typed `final` declaring parameters. Required positional parameters,
+required named parameters, and a mixture of both are supported. A constant
+primary constructor is also valid. Classes cannot have inheritance, mixins,
+implemented interfaces or members in their body. Add application behavior with
+Dart extensions; arbitrary constructor logic is outside the database decoder's
+contract.
+
+Annotations use the same validation for classes and Records. Built-in values,
+enums and explicit `@UseCodec` domain values retain their resolved Dart types.
+The generator checks codec compatibility without executing codecs. It rejects
+ambiguous field names, duplicate physical columns, invalid generated identities,
+nullable primary keys, computed-column/default conflicts, invalid selectors and
+foreign keys without a matching target key.
+
+Dart analysis rejects wrong create/patch value types, unknown query fields and
+assignment of an unrelated model with the same fields. Generation rejects
+unsupported declaration forms and database-schema conflicts. Database-specific
+capabilities are checked when selecting the migration engine.
+
+These are ordinary classes: the ORM does not generate equality, `copyWith`, JSON
+serialization or a global identity map. Two separately read rows are separate
+instances. Serialization remains application code, while column codecs control
+database encoding. In particular, SQL NULL, an omitted insert value and a missing
+JSON property are different concepts.
+
+## Records and schema history
+
+Named Record typedefs remain an explicit structural data form:
+
+```dart
+typedef Coordinate = ({@Id() int id, double x, double y});
+final coordinates = entity();
+```
+
+They share the same schema validation and query runtime. A Record typedef does
+not create nominal identity; another typedef with the same shape is assignable.
+Classes are the default for models and catalog-import drafts. Records are useful
+for projections and fixed SQL result shapes.
+
+Changing a row declaration from a Record to a class does not change its physical
+schema. Snapshots and saved migrations contain standalone physical metadata,
+without imports of current model classes, constructors, codecs or client-default
+functions. A class field rename can retain the database column with
+`@ColumnName('old_name')`; absent that explicit name, normal schema diff rules
+apply and never infer a destructive rename.
+
+Class fields support Dart's normal symbol navigation and rename tools.
+Regenerate after edits and repair affected generated-API references; a model
+rename does not promise that an IDE will edit the regenerated client or all its
+consumers automatically.
+
+## Earlier authoring experiment
+
+`dart run tool/compare_authoring.dart` retains the controlled comparison of Record,
+primary-constructor and typed-table-field declarations. Its adapter deliberately
+normalizes all three forms to Records so their output can be compared. It is an
+experiment, not the production class reader.
+
+The historical [report](../research/benchmarks/authoring.json) records sources,
+LSP edits, byte-identical physical snapshots and stale-consumer errors on Dart
+3.13.3. Its measurements establish neither universal brevity nor a generation
+speed ranking. The production generator now reads class parameters directly and
+constructs the declared model type.
diff --git a/docs/backfills.md b/docs/backfills.md
new file mode 100644
index 00000000..df3a9a50
--- /dev/null
+++ b/docs/backfills.md
@@ -0,0 +1,138 @@
+# Resumable backfills
+
+`Backfill` is an explicit migration step for a long data update. It commits small
+batches with durable primary-key cursors and verifies completion before recording
+the migration as applied. Import `package:orm/migrate.dart` alongside your database
+entry point.
+The examples use a raw `SqlDatabase` named `db`; for an ORM `Database`, pass
+`db.sql` to `Migrator`. MySQL/MariaDB recovery details are documented in
+[their migration guide](mysql-migrations.md).
+
+```dart
+// Use the snapshot committed with the expand migration, not current app models.
+final historical = expand.snapshot!;
+final users = historical.tables.singleWhere((t) => t.name == 'users');
+final backfill = Migration.steps(
+ '0003_display_names',
+ [
+ Backfill(
+ users,
+ set: {'display_name': 'name'},
+ where: 'display_name IS NULL',
+ doneWhen: 'SELECT NOT EXISTS(SELECT 1 FROM users WHERE display_name IS NULL)',
+ batchSize: 1000,
+ ),
+ ],
+ dialect: expand.dialect,
+ previous: expand.checksum,
+ snapshot: historical,
+);
+```
+
+Save this migration with `writeMigration` from `package:orm/generate.dart`, review
+the emitted Dart file, and import it through the static history on subsequent runs. Its table definition, assignments, filter, completion SQL and
+batch size are covered by the migration checksum. Expressions are trusted migration
+SQL for this history's chosen database.
+No latest generated client or application codec callback is needed to resume.
+
+## Running a bounded amount of work
+
+```dart
+final appliedIds = await Migrator(db).apply(
+ migrations,
+ maxBackfillBatches: 10,
+);
+final pending = await Migrator(db).plan(migrations);
+final checkpoints = await Migrator(db).progress();
+```
+
+The default completes all pending work. `maxBackfillBatches` limits the number of
+nonempty data batches performed by this call, shared across backfill steps. It
+does not change the saved migration or its checksum. The call returns IDs of
+migrations it completed; a paused migration remains pending. Completion verification
+may need the next call after the final permitted data batch. A batch limit is not
+a wall-clock or statement timeout.
+
+```sh
+dart run bin/migrate.dart plan
+dart run bin/migrate.dart apply --max-backfill-batches 10
+dart run bin/migrate.dart status
+```
+
+Configure PostgreSQL in the Dart entrypoint as described in [migrations](migrations.md).
+Plans report `atomic: false` when pending work includes a backfill. Bounded CLI
+runs additionally return `complete: false` until the entire migration list is
+applied. Status includes `backfill.rows`, `batches`, `last` and `upper`. Keys are
+stored as lossless strings; binary keys use base64, and integer keys never pass
+through floating-point JSON. These records contain primary-key data. A `running`
+checkpoint describes unfinished durable work; it is not proof of a live process.
+
+## Transaction and recovery behavior
+
+The runner checks the historical schema, captures an upper primary-key boundary,
+and scans matching keys in ascending order from the last committed key. Composite
+primary keys use row comparisons. There is no growing OFFSET. Actual batch sizes
+are reduced to fit the driver's parameter limit. SQLite documents this use of
+[row values for scrolling queries](https://www.sqlite.org/rowvalue.html).
+
+Each batch selects keys, updates exactly those rows and records its new cursor
+in one transaction. PostgreSQL locks selected rows without skipping locked rows;
+SQLite uses BEGIN IMMEDIATE for the batch. Skipping locked rows would be unsafe
+for a cursor that advances past them. See PostgreSQL's
+[row-locking semantics](https://www.postgresql.org/docs/current/sql-select.html).
+The whole invocation retains one leased connection, while other connections can
+operate between batch commits. SQLite runners recheck history and progress inside
+their write transaction; PostgreSQL runners retain the existing migration advisory
+lock. Competing runners do not repeat committed batches.
+
+A process exit during a batch rolls back both its writes and cursor. An exit after
+commit preserves both. A lost commit acknowledgement remains an error; a later
+invocation reads durable state to decide where to resume. It never assumes that
+an uncertain batch should be replayed. Successful chunks invalidate relevant typed
+query subscriptions after commit; rolled-back chunks do not publish their writes.
+
+An explicit backfill makes its containing migration recoverable rather than atomic
+as a whole. Other steps in that migration have individual checkpoints. Adjacent
+ordinary migrations retain their atomic grouping. SQLite table rebuilds remain
+whole-table operations with foreign-key verification and setting restoration;
+`batchSize` does not make a rebuild incremental.
+
+## Completion and constraints
+
+`doneWhen` must return exactly one boolean: a PostgreSQL boolean, or SQLite's integer
+0/1 representation. NULL, floating-point values and wrong result shapes are errors.
+A false condition leaves the migration pending with a failed verification checkpoint.
+Already committed batches stay committed. Repair the condition or missing data and
+resume the unchanged migration; the runner does not rewind and risk repeating
+non-idempotent updates.
+
+Primary keys must be non-null, unique across the scan and immutable throughout the
+operation, including application writes and triggers. Assigning a primary key is
+rejected. The runner checks updated/retained keys and rejects detected key movement.
+Integer, bigint, text, finite real, boolean, UTC instant, historical timestamp, local date/time and binary cursors are
+supported, including composite keys. JSON keys are rejected because the current
+driver boundary cannot promise lossless cursor representation for every document.
+Ordering follows the actual database storage type and collation.
+
+Use expand → compatible application writes → backfill → contract. New writes must
+already satisfy the intended invariant, including rows inserted behind the cursor
+or above the captured boundary. Completion SQL must cover that invariant. Keep
+the historical table/key definition stable while the job runs. Temporary tables
+cannot shadow the data target or durable migration metadata. PostgreSQL backfills
+reject active row security rather than letting hidden rows satisfy a false
+completion claim; the check uses the current role's
+[row-security state](https://www.postgresql.org/docs/current/functions-info.html).
+
+The historical catalog check happens at the start of each backfill attempt; normal
+chunks do not rescan the catalog. The runner bounds returned key rows and update
+parameters. Filter and verification SQL may still scan substantial data: inspect
+their query plans and add appropriate indexes as reviewed migrations. This feature
+does not promise a particular throughput, zero downtime, or automatic repair of an
+incorrect transformation. Statement timeouts and lock waits retain driver behavior.
+
+Reproduce the standalone SQLite native acceptance check with:
+
+```sh
+dart build cli --target test/support/native_backfill.dart --output .dart_tool/backfill-aot
+.dart_tool/backfill-aot/bundle/bin/native_backfill
+```
diff --git a/docs/capabilities.md b/docs/capabilities.md
new file mode 100644
index 00000000..8b81d1f9
--- /dev/null
+++ b/docs/capabilities.md
@@ -0,0 +1,114 @@
+# Capability review
+
+The acceptance scope comes from the [original design](../research/new-dart-orm-design.md).
+Its common relational lifecycle is implemented in one package. Optional backend
+extensions and untested deployment targets are not implied by a generic driver
+or a successful test on another platform.
+
+## Values and physical storage
+
+| Design §5 requirement | Implementation and evidence | Explicit boundary |
+| --- | --- | --- |
+| Integer widths and web-safe exact values | `IntegerBits`, integer/BigInt codecs, integer/native/browser checks, catalog metadata and reviewed migrations | Native `int` is signed 64-bit; JS-safe `int` is narrower. BigInt uses exact digits, but SQLite BigInt text does not promise numeric ordering/arithmetic. |
+| Exact decimal | Exact storage, comparisons, keys and generated/imported metadata on all four engines; arithmetic, aggregates/windows and rounding on SQLite/PostgreSQL | MySQL/MariaDB reject operations that can silently lose precision, including arithmetic, SUM, explicit narrowing and decimal set operations. See [engine limits](mysql.md) and [reproductions](../research/mysql-precision-boundaries.md). |
+| Distinct instant/date/time/local timestamp | UTC DateTime, LocalDate/LocalTime/LocalDateTime, explicit temporal precision, native binary decoding, SQLite collations, catalog/import/migration tests and browser transport | An IANA zone name is a separate application value, not an instant or local clock value. Calendar SQL arithmetic and timezone-rule conversion have no typed API. |
+| JSON versus arbitrary objects | SqlJson distinguishes JSON null from SQL NULL; explicit domain codecs validate custom objects, including generated create/result/relationship types | A Dart Map is not an automatic entity mapping. Backend-specific JSON path APIs are extensions. |
+| Stable enum text | EnumValue labels and checked enum codecs; generated/native/negative tests | Native PostgreSQL enums require separate metadata and migration support. |
+| Binary and custom IDs | Uint8List and public const UseCodec declarations, checked domain codecs, generated type failures, native/browser reads/writes/relations | A codec's semantic change is not automatically a DDL change. Custom equality/order must match the declared storage. |
+
+The authoritative contracts and tests are indexed in [types](types.md),
+[decimals](decimals.md) and the [acceptance map](acceptance.md). The design's time
+contract specifies storage distinctions and precise codecs; it does not define a
+timezone database or a calendar SQL function family. Earlier progress notes
+listed those possible extensions as open-ended follow-up work. They remain
+explicitly unimplemented rather than being counted as delivered functionality.
+
+Catalog import recognizes supported physical representations without sampling
+data to guess semantics. Ordinary SQLite INTEGER/TEXT cannot prove a boolean,
+enum, timestamp, BigInt or JSON domain. Unsupported VARCHAR/arrays/domains and
+unsupported identity/table forms produce explicit issues instead of silently
+changing their meaning. Reviewed annotations/codecs and migrations remain part
+of adopting an existing database; import is not a universal database backup.
+
+## Query and execution contract
+
+| Required family | Evidence and available behavior | Boundary |
+| --- | --- | --- |
+| Scalars, Records, DTOs and dynamic selection | `selection_test`, generated/native tests; mappers run only after rows arrive | Dynamic field sets return a dynamic map, not invented static fields. |
+| Conditions, ordering and pagination | Database/type/cursor suites, stable unique tie breakers, explicit NULL order | Offset pages do not provide a snapshot; cursor order needs declared keys. |
+| Joins, grouping/HAVING, subqueries, CTEs, windows, UNION | `test/support/advanced.dart`, set and numeric suites on both backends; SQL scope and aggregate validation | INTERSECT/EXCEPT and arbitrary database functions do not have dedicated typed methods. Parameterized raw/named SQL is the formal extension path. |
+| Relations and relation ordering | Joined or batched to-one; batched collections, composite/self/multiple edges, many-to-many payloads, per-parent limits, any/none/every/count | Order root rows through a typed alias or correlated count. Loaded Record fields are not SQL expressions. No cross-database relation or invisible lazy I/O. |
+| Writes and transactions | Generated create/patch, explicit NULL/default, computed/client defaults, batch/upsert/RETURNING, savepoints, rollback, escaped-session rejection | No graph tracking, implicit flush or distributed transaction. |
+| Failure handling and streaming | Real interruption, unknown commit, bounded acquisition/retries, real cursors and awaited cleanup | An external side effect is not rolled back by SQL or safe to repeat automatically. Web interruption and MySQL/MariaDB streaming/cancellation are unsupported and rejected. |
+| Plans and observations | SQL/column/key/join/batch descriptions and actual acquisition/query/decode events | No general optimizer, result cache or hidden EXPLAIN ANALYZE. Timing scopes are documented, not total CPU attribution. |
+
+See [query examples](queries.md), [relationships](relations.md),
+[execution](execution.md) and [observability](observability.md).
+
+SQLite cancellation is a build capability, not a promise for every native target.
+The default Linux asset in `sqlite3` 3.6.0 hides `sqlite3_interrupt`; it rejects
+statement cancellation, execution deadlines and bounded retries before SQL starts.
+Ordinary transactions and streaming still work. macOS and Android interruption
+have separate runtime evidence; see [execution](execution.md).
+
+## Migration and database adoption
+
+Each history fixes one database engine, even when empty. A saved migration contains
+one step list and only that engine's frozen physical expressions. Mixed histories
+and mismatched connections fail before migration SQL. PostgreSQL migration
+execution requires 18+, and SQLite opening requires 3.35+; arbitrary reviewed SQL
+can require additional capabilities.
+
+MySQL 8.4+ and MariaDB 10.6+ use separate driver identities. Migration execution
+requires MySQL 8.4+ or MariaDB 11.8+. Their DDL can commit implicitly: checked
+before/after table metadata and durable checkpoints support recovery, while
+backfill writes and completion checkpoints
+share a transaction. See [MySQL/MariaDB migrations](mysql-migrations.md). Current
+live acceptance uses MySQL 8.4 and MariaDB 11.8; the MariaDB driver's lower
+connection minimum has not received that full acceptance suite.
+
+Saved migrations contain immutable snapshots, operations, predecessor checksums
+and explicit renames/conversions. Tests exercise fresh replay, older-version
+upgrades, safe SQLite rebuilds, PostgreSQL constraint/catalog behavior, baseline,
+drift, version compatibility, durable backfills and nontransactional recovery.
+The migration CLI and real build_runner process workflows test application-facing
+commands, including failure repair and stale-output cleanup.
+
+Unmanaged views, triggers, specialized indexes, policies and table options require
+review. PostgreSQL policy reports now retain roles, command, mode and expressions,
+plus enabled/forced row-security flags. Actual triggers are created and exercised
+after read-only import/verification on both backends. Baseline verifies declared
+schema facts and returns unmanaged metadata; it does not recreate or certify
+grants, every extension, authorization behavior or the whole database environment.
+
+## Platform and tooling scope
+
+Native SQLite and PostgreSQL are checked against SQLite 3.53.4/PostgreSQL 18.4.
+MySQL 8.4 and MariaDB 11.8 have separate live driver, typed query, import,
+transaction and migration-recovery suites.
+Browser reports cover real Chrome JS and Dart WASM, worker memory/OPFS storage,
+reopen, interruption recovery, upgrade and watch. Android Flutter checks cover
+actual debug-to-AOT APK replacement and independent-process restart. These do
+not certify every database version, browser, physical device, iOS or macOS Flutter.
+Current source/validation revisions are recorded in [progress](progress.md).
+Each platform capture is tied to its recorded source revision; consult the latest
+acceptance record before relying on a historical platform result.
+
+Driver configuration is typed and explicit. PostgreSQL reuses its driver's pool,
+offers borrowed-pool ownership and certificate-verifying TLS by default; SQLite
+owns one background connection behind a unified native/browser entrypoint.
+Memory and named persistent settings are shared; native paths remain explicit.
+Flutter Web bundles default assets, with optional browser resource overrides. URL options are
+not silently merged with typed settings. MySQL/MariaDB own one queued physical
+connection each, with certificate-verifying TLS by default and explicit capability
+limits. Unsupported transports, serverless sessions, replica routing and additional
+connection-pool variants need their own adapters and verification.
+
+Generation and completion measurements cover 10/100/1000 models. The declaration
+experiment normalized three input forms to identical generated APIs. The current
+package supports ordinary immutable model classes with nominal results, alongside
+Record declarations; see [authoring](authoring.md). Named Record field rename is unavailable
+in the checked SDK. The captured same-session class rename timeout has a checked
+server-restart path; it is not described as a working general IDE workflow.
+Runtime cost reports compare identical SQL/driver/result workloads, including a
+controlled TCP delay, with their sampling and allocation limits stated explicitly.
diff --git a/docs/checks.md b/docs/checks.md
new file mode 100644
index 00000000..43b918f7
--- /dev/null
+++ b/docs/checks.md
@@ -0,0 +1,94 @@
+# Row CHECK constraints
+
+Declare a row constraint beside its entity. Expressions use physical SQL column
+names; generation reads literal SQL and never executes a sample Dart record.
+
+```dart
+typedef Product = ({
+ @Id.generated() int id,
+ double price,
+ double? discount,
+ String label,
+});
+final products = entity();
+final nonnegativePrice = products.check('price >= 0');
+final validDiscount = products.check('discount >= 0 AND discount <= price');
+final shortLabel = products.check(
+ 'length(label) <= 20',
+ postgres: 'char_length(label) <= 20',
+);
+```
+
+`name` defaults to the declaration's snake_case name, for example
+`nonnegative_price`. Set an explicit stable name to rename the Dart declaration
+without renaming its database constraint. `name: null` deliberately emits an
+unnamed constraint. Names must be nonempty and unique per table. SQLite compares
+ASCII identifier case without distinction; PostgreSQL preserves quoted case.
+Expressions and optional overrides are string literals. An override replaces the
+common expression for that backend; the expression selected by the migration
+target must be nonempty.
+
+These are trusted schema SQL fragments, like `@Default.sql`; do not construct
+them from user input. Dart checks the declaration API, while the database checks
+SQL syntax and enforces the predicate. This feature does not type-check SQL column
+names or translate arbitrary Dart boolean closures.
+
+SQL NULL is accepted by CHECK. A nullable `discount` can be absent in this example;
+requiring a value needs a non-nullable field as well. Constraints concern the
+current row and should use stable functions. PostgreSQL assumes a CHECK condition
+does not change for the same row; changing a function implementation requires
+explicit revalidation. See [PostgreSQL constraints](https://www.postgresql.org/docs/18/ddl-constraints.html)
+and [SQLite CHECK semantics](https://www.sqlite.org/lang_createtable.html#check_constraints).
+
+## Snapshots, verification and import
+
+The current generated `TableSchema.checks` retains overrides in `CheckSchema`.
+Saved migration schemas freeze only their chosen engine's expressions. Changing
+an unused override does not change that migration target's physical fingerprint.
+
+`inspectTable` and `orm db inspect` expose native names and expressions.
+`verifySchema` compares declared checks, including duplicate unnamed constraints.
+An extra check is reported as an unmanaged object; a missing or different check
+is drift. PostgreSQL unvalidated, unenforced, inherited and NO INHERIT constraints
+stay unmanaged because they do not meet this declaration's ordinary enforced-row
+contract.
+
+SQLite comparison tokenizes SQL, ignores comments, identifier quoting and outer
+parentheses, and retains string literals, casts and precedence. It preserves
+SQLite's non-ASCII identifier case distinctions. This is conservative comparison,
+not a general SQL parser or proof that differently written predicates are equivalent.
+The exact unnamed range/precision expressions emitted for `@IntegerBits` and
+`@DecimalDigits` remain reserved storage metadata; named row checks are separate.
+
+PostgreSQL rewrites SQL when storing a constraint. Verification uses one
+`EXPLAIN (VERBOSE, FORMAT JSON)` projection per checked table to render declared
+and catalog expressions in the same typed context. It has planning/catalog cost
+and does not execute the SELECT or scan application rows. The planner can evaluate
+immutable constant expressions, so this is not a promise of zero function
+evaluation. No `ANALYZE` option is used. See [EXPLAIN](https://www.postgresql.org/docs/18/sql-explain.html).
+SQL/functions must be available in the selected database schema during verification.
+
+[Import](importing.md) retains native check SQL and names, including explicit null
+names on SQLite, and emits a nonblocking `IMPORT.CHECK_SQL` review note. Check
+other-dialect overrides before deploying an imported declaration elsewhere.
+
+## Reviewed migrations and cost
+
+`Migration.diff` includes additions, removals and expression/name changes.
+PostgreSQL drops changed constraints and adds replacements. SQLite rebuilds the
+table. Adding a check validates existing rows; a violation rolls back the ordinary
+migration batch and its history. Repair data explicitly, then retry the unchanged
+migration. A change to only the PostgreSQL expression produces no SQLite DDL.
+
+For an explicit table/column rename, update physical names in the declared SQL.
+The diff removes old declared checks before native renames and adds the new
+expressions afterward. It never guesses how to rewrite SQL text. On SQLite a
+checked rename with target checks uses two visible rebuild steps, potentially
+copying the table twice; inspect the migration and budget disk space and write
+lock time. Native renames preserve view, trigger and foreign-key references.
+Unclaimed checks block a SQLite rebuild instead of being silently removed.
+
+Checks can make writes and schema upgrades more expensive. This API provides
+reviewed, transactional changes; an online zero-lock upgrade is not implied.
+Function definitions, cross-table invariants and specialized constraint modes
+remain explicit native migration work.
diff --git a/docs/cli.md b/docs/cli.md
new file mode 100644
index 00000000..93a273de
--- /dev/null
+++ b/docs/cli.md
@@ -0,0 +1,135 @@
+# Project CLI
+
+Start inside a Dart project with the `orm` dependency and Dart 3.13 or newer:
+
+```sh
+dart run orm init --database sqlite
+dart run orm migrate create 0001_initial
+# Review migrations/m0001_initial.dart before applying it.
+dart run orm migrate apply
+dart run orm migrate verify
+```
+
+`init` also accepts `postgres`, `mysql` and `mariadb`. It creates five files:
+
+| File | Purpose |
+| --- | --- |
+| `lib/schema.dart` | Editable nominal Dart model and table declaration |
+| `lib/schema.orm.dart` | Generated typed query client |
+| `lib/schema.snapshot.dart` | Standalone physical schema |
+| `migrations/migrations.g.dart` | Static imports and one fixed engine |
+| `orm.config.dart` | Typed project configuration and executable entrypoint |
+
+Initialization refuses an existing destination before writing anything. It never
+connects to a database, creates a database file or applies DDL. The first client
+and snapshot are generated before writing the config, so its static imports are
+valid immediately. No JSON schema loader, reflection, package-specific runtime
+registration or build_runner setup is needed for this workflow.
+
+SQLite defaults to `app.sqlite`; edit its typed options in the config to change
+the path. Server connections read `DATABASE_URL` only when connecting. Missing
+credentials do not prevent initialization, generation or history validation.
+TLS defaults to certificate verification. Connections use the independent driver
+and `SqlDatabase` layers rather than importing model/query APIs.
+
+## Typed configuration
+
+The generated `orm.config.dart` is normal application-owned Dart:
+
+```dart
+import 'package:orm/cli.dart';
+import 'package:orm/drivers/sqlite.dart';
+import 'lib/schema.snapshot.dart' as target;
+import 'migrations/migrations.g.dart';
+
+Future main(List args) => runOrmCli(args, config: OrmConfig(
+ schema: 'lib/schema.dart',
+ migrations: 'migrations',
+ history: migrationHistory,
+ snapshot: target.schema,
+ connect: ({required bool readOnly}) async => SqlDatabase(
+ await SqliteDriver.open(readOnly
+ ? const SqliteOptions.readOnly('app.sqlite')
+ : const SqliteOptions.file('app.sqlite')),
+ ),
+));
+```
+
+The package command runs this explicit entrypoint in a child Dart process.
+History is statically imported and checked; it is not discovered by executing
+every Dart file in a directory. Run from the project root so relative schema,
+history and connection paths are consistent. Use `--config other.config.dart`
+for another explicitly selected entrypoint, or run
+`dart run orm.config.dart migrate check` directly.
+
+Config is trusted project source and should not perform I/O at the top level.
+Place connection setup inside `connect`. Migration commands establish their own
+transaction and locking behavior; `readOnly` lets a SQLite factory avoid creating
+a file during inspection.
+
+## Commands and side effects
+
+| Command | Behavior |
+| --- | --- |
+| `generate` | Generate client and physical snapshot using the config |
+| `migrate create ` | Regenerate the current schema, then save its diff as fixed Dart history |
+| `migrate check` | Check compiled history and fingerprints without a connection |
+| `migrate plan` | Read applied history and report pending operations |
+| `migrate apply` | Apply pending operations explicitly |
+| `migrate status` | Read migration history and recovery checkpoints |
+| `migrate verify` | Compare the catalog with the generated snapshot |
+| `migrate baseline` | Verify an existing schema and register its history |
+| `migrate record ` | Record a reviewed edit to the latest unpublished migration |
+| `migrate inspect ` | Read physical metadata for one table |
+
+`create` always uses the current source, including edits since the last
+`generate`. Other commands use the statically imported snapshot/history; they do
+not silently regenerate or change deployment artifacts. Run `generate` before
+checking a deliberately edited target with `verify`. New migrations never
+overwrite existing files. Database changes happen through explicit `apply` or
+`baseline`; initialization, generation and diff creation are offline.
+
+An initial SQLite `plan` needs an existing file and fails without creating one.
+The first `apply` can create that file. `create --allow-destructive` permits
+writing reviewed drop operations, not executing them. `apply
+--max-backfill-batches ` bounds a resumable backfill invocation.
+
+See [migrations](migrations.md) for immutable history, engine boundaries, reviewed
+renames/conversions, baseline and recovery behavior.
+
+## Explicit tools
+
+These commands also work without project configuration:
+
+```sh
+dart run orm generate lib/schema.dart lib/generated/database.dart
+dart run orm migration registry migrations --dialect sqlite
+dart run orm db inspect --sqlite app.sqlite --table tasks
+dart run orm db import --sqlite app.sqlite --output lib/imported.dart
+dart run orm queries generate lib/queries.dart
+dart run orm queries check --source lib/queries.dart --sqlite app.sqlite
+dart run orm web-assets web/orm
+```
+
+Server database flags are `--postgres-env NAME`, `--mysql-env NAME` and
+`--mariadb-env NAME`. Choose exactly one database option. `--tls
+verifyFull|require|disable` configures server TLS; `--database-schema` is specific
+to PostgreSQL. Catalog import writes a Dart draft and a separate review report.
+It does not migrate an existing database.
+
+Without a config, `generate` uses `lib/schema.dart`. If a config's generated
+snapshot was deleted, recover with the explicit source command
+`dart run orm generate lib/schema.dart`, which does not load that config.
+
+## Help and automation
+
+`dart run orm --help`, `dart run orm help migrate` and `dart run orm migrate
+apply --help` describe command groups. Add `--json` to emit machine-readable
+reports on stdout and error objects on stderr. JSON is a reporting format only;
+schema snapshots and migration history remain Dart source.
+
+Exit codes are `0` for success, `1` for execution/generation failure, `2` for
+catalog drift or blocking import issues, and `64` for invalid arguments or
+configuration. The Dart launcher may print native build-hook diagnostics on
+stderr before the CLI starts; automation should parse successful stdout reports
+and use the process exit code for failures.
diff --git a/docs/computed.md b/docs/computed.md
new file mode 100644
index 00000000..c11d96ed
--- /dev/null
+++ b/docs/computed.md
@@ -0,0 +1,100 @@
+# Database computed columns
+
+Declare SQL over physical column names. The generated Record includes the result;
+creation and patch inputs omit it.
+
+```dart
+typedef Line = ({
+ @Id.generated() int id,
+ int price,
+ int quantity,
+ String label,
+ @Computed.sql('price * quantity') int total,
+ @Computed.sql('length(label)', postgres: 'char_length(label)',
+ storage: ComputedStorage.virtual) int labelSize,
+});
+final lines = entity();
+
+final row = await db.lines.create(price: 4, quantity: 3, label: 'cat');
+print(row.total); // 12
+await db.lines.byId(row.id).patch(quantity: .set(5)); // total becomes 20
+final totals = await db.lines.select((r) => r.total).get();
+```
+
+`ComputedStorage.stored` is the ORM default and computes on writes; `virtual`
+computes on reads. Both modes emit an explicit SQL storage clause. Select based
+on expression cost, read/write frequency and storage needs. PostgreSQL 18 and
+SQLite support both, but PostgreSQL 18 rejects indexes/unique keys on virtual
+columns. Use stored columns for that portable schema. No performance advantage
+is assumed from these correctness tests.
+
+Generated computed fields are `ReadField`: they support expressions, ordering,
+selection and relationship keys, but have no `set`, `increment`, `change` or
+`defaultValue` method. They cannot coexist with identity, SQL defaults or client
+factories. SQLite cannot use computed primary keys; PostgreSQL permits stored
+computed primary keys. Every table needs an ordinary column. Generation preserves
+these declarations and the migration target enforces the selected engine's rules.
+Raw SQL retains the database's own write rules.
+
+SQL is trusted schema code. Generation reads the literal; it does not translate
+Dart closures or validate SQL function volatility. The database validates names,
+operators and determinism. PostgreSQL disallows references to another generated
+column and restricts virtual expressions to built-in functions/types. SQLite has
+its own deterministic-expression rules. Review overrides for each backend.
+[PostgreSQL rules](https://www.postgresql.org/docs/18/ddl-generated-columns.html),
+[SQLite rules](https://www.sqlite.org/gencol.html).
+
+## Migration behavior
+
+Current generated snapshots retain expression overrides and the storage mode.
+Each saved migration freezes only its selected engine's expressions.
+
+| Change | PostgreSQL | SQLite |
+| --- | --- | --- |
+| Add a computed column | Native ADD COLUMN; old rows get computed values | Virtual: ADD COLUMN. Stored: rebuild |
+| Change expression | SET EXPRESSION AS; stored values are rewritten | Rebuild, recomputing target columns |
+| Change computed result type | Native TYPE without USING, followed by target expression | Rebuild with target expression |
+| Drop a computed column | Explicit destructive diff, native DROP COLUMN | Explicit destructive diff, rebuild |
+| Stored to ordinary | DROP EXPRESSION retains existing values | Rebuild copies the old computed values |
+| Ordinary to computed, storage-mode change, virtual to ordinary | Automatic diff requires a reviewed replacement/materialization plan | Automatic rebuild; discarding ordinary stored values requires `allowDestructive` |
+
+The PostgreSQL diff refuses mode transitions that cannot be emitted natively.
+Use reviewed `Migration.steps` with explicit operations for that history's engine;
+preserve indexes, constraints, views and triggers when replacing a column. Changing
+types of columns used by generated expressions can also require a manual plan due
+to native dependency rules. Automatic TYPE assumes the database accepts the cast;
+it is not a promise of a lossless type conversion.
+
+Stored-to-ordinary type changes still require explicit `using` conversions. A
+computed target derives values from its declared expression and rejects `using`.
+Rebuild copy maps and Backfill assignments must omit computed target columns.
+Adding a computed non-null column needs no invented default/backfill: the
+expression supplies values for old rows, and invalid results abort the migration.
+
+Explicit renames require the target declaration's updated SQL; the ORM never
+rewrites arbitrary expression text. PostgreSQL performs native renames and updates
+the target expression. SQLite first materializes old computed values, performs
+the rename, then rebuilds using the target expressions. A renamed computed table
+can be copied twice; related CHECK preparation shares the first copy. Plan this
+I/O and lock time before applying a large migration.
+
+Tests run against PostgreSQL 18.4 and the pinned SQLite engine. PostgreSQL migration
+execution requires server 18 or newer. Unsupported native syntax fails the
+migration; there is no silent emulation. Stored expression changes rewrite rows and PostgreSQL
+discards their column statistics, so review post-migration ANALYZE needs.
+[Native ALTER TABLE behavior](https://www.postgresql.org/docs/18/sql-altertable.html).
+
+## Catalogs and imports
+
+`inspectColumns` exposes `ColumnInfo.computed`; `db inspect` includes expression
+and mode. `verifyColumns` and `verifySchema` compare computation metadata in
+addition to existing column facts. PostgreSQL uses a single EXPLAIN projection
+per computed table, including assignment casts, to compare native typed output.
+This plans SQL without selecting rows; immutable constant functions may run during
+planning. SQLite compares tokenized SQL and preserves precedence, comments and
+quoted identifiers. Semantically equivalent rewrites are not always recognized.
+
+`db import` emits `@Computed.sql` and a nonblocking `IMPORT.COMPUTED_SQL` review
+note. SQL from one database is not evidence of portability to the other. Managed
+Decimal coercion is unwrapped for declarations and emitted once on regeneration.
+Import does not run application code or sample data values.
diff --git a/docs/decimals.md b/docs/decimals.md
new file mode 100644
index 00000000..46074184
--- /dev/null
+++ b/docs/decimals.md
@@ -0,0 +1,308 @@
+# Exact decimals
+
+`Decimal` stores a normalized BigInt coefficient and decimal scale. Construction,
+typed writes and reads never pass through `double`. Equal values such as `2`,
+`2.00` and `20e-1` have the same equality and hash code. Display precision is not
+retained; `toString()` produces ordinary canonical decimal text.
+
+The SQL arithmetic examples below apply to SQLite and PostgreSQL. MySQL/MariaDB
+support exact values, storage, comparisons and MIN/MAX within 65-digit/30-scale
+limits, require declared column precision, and reject typed operations that can
+silently lose precision. See [engine-specific boundaries](mysql.md). Pure Dart
+`Decimal` value arithmetic is independent of the selected database.
+
+```dart
+import 'package:orm/schema.dart';
+
+typedef Invoice = ({
+ @Id.generated() int id,
+ Decimal total,
+ Decimal? discount,
+});
+final invoices = entity();
+
+// After generation:
+await db.invoices.create(total: Decimal.parse('9007199254740993.01'));
+final total = await db.invoices.select((i) => i.total.sum()).single();
+```
+
+Use `Decimal.parse(String)` or `Decimal.fromBigInt(value, scale: 2)`.
+Scientific notation is accepted. Whitespace, NaN, Infinity and floating-point
+codec inputs are rejected. The supported finite range is at most 131072 integer
+digits and 16383 fractional digits, matching unconstrained PostgreSQL
+[NUMERIC limits](https://www.postgresql.org/docs/current/datatype-numeric.html).
+Parsing also bounds input length and exponents. Out-of-range arithmetic throws;
+there is no saturation or automatic precision reduction.
+
+## Arithmetic
+
+Value operations `+`, `-`, `*`, comparisons and sorting are exact. Division and
+rounding require an explicit scale and default to rejecting a discarded nonzero
+remainder:
+
+```dart
+final third = Decimal.parse('1').divide(
+ Decimal.parse('3'),
+ scale: 8,
+ rounding: DecimalRounding.halfEven,
+); // 0.33333333
+final cents = Decimal.parse('2.345').rounded(
+ 2,
+ rounding: DecimalRounding.halfEven,
+); // 2.34
+```
+
+Other modes are `exact`, `towardZero`, `floor`, `ceiling` and
+`halfAwayFromZero`. Negative scales round integer digits. Rounding changes the
+value, not its display padding.
+
+SQL fields provide `plus`, `minus`, `times`, `plusExpression`, `minusExpression`
+and `timesExpression`. Combining expressions can produce SQL NULL and returns a
+nullable decimal expression. `sum(distinct: true)` is optional; empty/all-null
+sums return null. Aggregate accumulation permits temporary overflow that cancels
+before a valid final result; range checks apply when producing the result. `min`, `max`, `count`, grouping and aggregate windows compose
+with the existing query API. Predicates, IN/subqueries, computed CTE references,
+UNIONs, streaming and transported cursors preserve decimal comparison semantics.
+
+SQL expressions also provide `divide`, `divideExpression` and `rounded`, with the
+same explicit scale and six rounding modes as values:
+
+```dart
+final installments = await db.invoices.select(
+ (i) => i.total.divide(
+ Decimal.parse('3'),
+ scale: 2,
+ rounding: .halfEven,
+ ),
+).get();
+final roundedTotal = await db.invoices.select(
+ (i) => i.total.sum().rounded(2, rounding: .halfEven),
+).single();
+```
+
+Scale is -131072..16383. The default `exact` rejects discarded nonzero digits;
+division by zero and a result outside the finite range fail the statement.
+`divideExpression` accepts a nullable decimal expression and returns a nullable
+result. SQL NULL propagates, including a null numerator with a zero divisor.
+Each operand is evaluated once for a division evaluation, including volatile
+PostgreSQL expressions. Expression assignments participate in ordinary transaction
+rollback. These methods also compose with grouping, windows, CTEs, sets, streamed
+results and per-parent relationship pagination.
+
+PostgreSQL division uses [integer quotients and exact remainders](https://www.postgresql.org/docs/current/functions-math.html), rather than
+rounding native `/`, whose chosen result scale can already have discarded digits.
+Large remainders use a bounded decomposition to avoid overflowing an intermediate
+product. Scalar stages use `MATERIALIZED` CTEs (PostgreSQL 12+); window operands
+are evaluated in the original query before the final scalar projection. This
+remains one statement and installs no database functions. It requires more SQL
+work than native limited-scale division; cost depends on row count, operand size
+and requested scale. SQLite calls the native worker's BigInt-based decimal
+functions. No floating-point fallback is used.
+
+Trusted raw SQL remains the caller's responsibility, including its result type.
+
+## Exact averages
+
+`average(scale: ..., rounding: ...)` returns `Expr`. It ignores SQL NULL
+and returns null for empty/all-null input, following normal
+[aggregate semantics](https://www.postgresql.org/docs/current/functions-aggregate.html).
+Scale is required; the default `exact` rejects a nonzero discarded remainder.
+All six rounding modes work across the full supported scale range.
+
+```dart
+final average = await db.invoices.select(
+ (i) => i.total.average(scale: 2, rounding: .halfEven),
+).single();
+final running = await db.invoices.orderBy((i) => [i.id.asc()]).select(
+ (i) => i.total.average(scale: 2, rounding: .halfEven).over(
+ orderBy: [i.id.asc()],
+ frame: .rowsToCurrent,
+ ),
+).get();
+```
+
+The result rounds once. It does not use a previously rounded native AVG or require
+the total to fit Decimal first: averaging two `9e131071` values succeeds even
+though their sum is outside the finite range. PostgreSQL splits each input into
+an integer high part and a low remainder at base 10^20, sums those parts and counts
+non-null inputs, then computes the exact quotient/remainder before rounding.
+The base exceeds the maximum signed 64-bit count; both component sums fit NUMERIC.
+This uses three native aggregates and no array of input rows or installed server
+function. SQLite maintains one BigInt accumulator plus count and uses an integer
+fraction to produce the final value. Sliding frames remove values incrementally.
+
+An input expression is evaluated once per contributing row for each average,
+including volatile PostgreSQL expressions. Ordinary PostgreSQL aggregation uses
+a correlated lateral input; window averages share their input, partition and order
+values in a preceding projection. Grouping/HAVING happens before the window;
+DISTINCT, final ordering and pagination apply to final results. Averages also work
+in CTEs, correlated scalar subqueries, batched relation windows and streamed results.
+Use a scalar subquery when assigning an aggregate result in a mutation.
+
+To average unique values, deduplicate the input projection first:
+
+```dart
+final unique = db.invoices.select((i) => i.total).distinct().asCte('unique_totals');
+final mean = await unique.query.select(
+ (i) => i.ref((source) => source.total).average(scale: 2, rounding: .halfEven),
+).single();
+```
+
+`distinct()` after the average instead deduplicates result rows. Window results
+must similarly become CTE/subquery columns before another aggregate consumes them.
+
+For application-side integer fractions, use
+`Decimal.fromFraction(numerator, denominator, scale: ..., rounding: ...)`.
+The numerator and denominator are BigInt values; only the final rounded result
+must fit the Decimal range. A zero denominator is rejected. This avoids constructing
+an out-of-range Decimal just to divide it back into range.
+
+## Column precision and scale
+
+Declare column precision independently of the Decimal value codec:
+
+```dart
+typedef Balance = ({
+ @Id.generated() int id,
+ @DecimalDigits(12, 2) Decimal amount,
+ @DecimalDigits(12, 2) @Default.sql("'1.235'") Decimal initial,
+});
+```
+
+Precision is 1..1000 and scale is -1000..1000. Omitting scale means zero.
+These are [PostgreSQL NUMERIC declarations](https://www.postgresql.org/docs/current/datatype-numeric.html):
+negative scale rounds integer digits, and scale may exceed precision. For example,
+`DecimalDigits(3, -2)` stores multiples of 100 through 99900 in magnitude;
+`DecimalDigits(3, 5)` stores up to 0.00999 in magnitude. Negative/excess scales
+require PostgreSQL 15 or newer. Native verification uses PostgreSQL 18.4.
+
+ORM writes round ties away from zero and then check the range. `1.235` becomes
+`1.24`, `-1.235` becomes `-1.24`; `999.995` overflows NUMERIC(5,2) after rounding.
+This applies to generated creation/patches, expression assignments, batches,
+upserts and defaults. Generated records contain the stored value; use the
+returned key if a decimal primary key was rounded. Query parameters are not
+implicitly rounded to a column's scale.
+
+Computed values and aggregates retain the unconstrained Decimal codec. A sum may
+therefore exceed the column's precision. To coerce a SQL expression explicitly,
+use `amount.sum().constrained(12, 2)`; this composes with predicates and CTEs.
+For an application value, `value.constrained(12, 2)` performs the same rounding
+and range check, while `value.fits(12, 2)` checks whether it fits without rounding.
+Choose `rounded(..., rounding: ...)` before a write when another rounding policy
+is needed. Column coercion then preserves the already rounded value.
+
+PostgreSQL uses native NUMERIC(p,s). SQLite uses the existing numeric TEXT
+collation plus a managed precision CHECK. ORM assignments and defaults call the
+exact coercion function. A raw SQLite writer must supply an already fitting value
+or explicitly call `orm_decimal_cast_v1(value, precision, scale)`; the CHECK
+rejects values requiring rounding, out-of-range values and invalid decimal text.
+A raw PostgreSQL writer receives PostgreSQL's native coercion. As with the native
+NUMERIC type, NaN remains a PostgreSQL write possibility and fails typed decoding.
+
+Precision/scale are included in snapshots, CLI inspection and import drafts.
+Changing either requires explicit migration conversion expressions. SQLite
+rebuilds and coerces the copied values; PostgreSQL changes the column type.
+Rounding can turn distinct keys into duplicates, which rolls back structure and
+history together. Imported SQLite declarations remove the managed outer default
+coercion before generation; verification still detects a missing coercion in the
+actual database default. Custom decimal-backed codecs retain their Dart types.
+
+## Storage and other database writers
+
+PostgreSQL uses native NUMERIC and its native arithmetic. SQLite uses TEXT with
+the versioned `orm_decimal_v1` numeric collation. Each native SQLite worker
+registers pure exact arithmetic functions and a window-capable sum. This is
+necessary because ordinary SQLite numeric operations can coerce text to
+[approximate floating point](https://www.sqlite.org/floatingpoint.html).
+Arithmetic and sum functions are restricted to direct SQL. Column coercion and
+validation functions additionally run in defaults and CHECK constraints. The
+current SQLite binding does not mark these two functions innocuous, so SQLite
+rejects their use in schema expressions with `trusted_schema = OFF`. The driver
+preserves that setting; constrained decimal schemas currently require it ON.
+
+The collation also governs indexes, primary/unique keys and foreign keys: `2.00`
+conflicts with `2`. Batch relationship keys normalize before matching returned
+rows. Applications opening these SQLite files through another driver must provide
+the same collation before using affected keys, sorting or schema changes. Raw
+decimal arithmetic additionally needs the corresponding functions. The native
+ORM driver registers these per connection; browser support has not been verified.
+
+Always bind strings for externally written decimal values. SQLite TEXT affinity
+cannot recover precision already lost in an incoming REAL value. SQL defaults
+should be quoted decimal strings, for example `@Default.sql("'0.10'")`.
+Ordinary numeric literals can be evaluated approximately by SQLite first.
+
+Unconstrained decimal columns have no generated finite-value CHECK. PostgreSQL
+permits special numeric values; unconstrained SQLite columns permit arbitrary text. Typed decoders
+reject these. SQLite orders invalid external text after valid decimals, using
+lexical order between invalid values, because a collation callback cannot report
+a SQL error safely. Arithmetic on invalid text fails. Do not treat the absence
+of a write error from another client as validation of a `Decimal` value.
+
+## Schema evolution and verification
+
+Snapshots store the `decimal` tag. Catalog verification checks SQLite column
+collation as well as storage type, nullability and other declared facts. Import
+recognizes PostgreSQL NUMERIC, optional precision/scale, and SQLite TEXT columns
+carrying the exact managed collation and optional managed precision check. Plain SQLite NUMERIC is not imported as an exact decimal.
+Quoted defaults or nested SQL fragments do not count as column collations.
+
+Changing text to decimal requires reviewed conversion expressions. SQLite rebuilds
+the table with the new collation; PostgreSQL changes its native type. Existing
+text keys `2` and `2.00` become duplicate numeric keys, so the migration fails and
+rolls back data, structure and history together. Repair the data before retrying.
+Historical backfills retain exact decimal keys in their resumable checkpoints.
+
+See the [generated fixture](../test/support/decimals/schema.dart),
+[database checks](../test/decimal_test.dart),
+[division/window checks](../test/decimal_division_test.dart),
+[average checks](../test/decimal_average_test.dart) and the
+[native acceptance executable](../test/support/decimals/native.dart).
+These establish correctness on the tested native databases. The real
+[JS/WASM capture](sqlite-web.md) additionally checks exact Decimal transport.
+It does not rerun this complete arithmetic/precision suite, and the Android
+Flutter acceptance does not include Decimal-specific scenarios.
+
+## Native cost probe
+
+The [benchmark script](../tool/benchmark_decimal.dart) fetches and decodes 10000
+integer-valued Decimal rows. Each case has one warmup and three measured runs.
+The checked-in [raw report](../research/benchmarks/decimal-division.json) was
+recorded with a native macOS ARM64 AOT executable, Dart 3.13.3, in-memory SQLite
+3.51.0 and local PostgreSQL 18.4. Median elapsed milliseconds:
+
+| Operation | SQLite | PostgreSQL |
+| --- | ---: | ---: |
+| Read Decimal values | 10.13 | 22.72 |
+| Divide by 3, scale 2, half-even | 30.09 | 32.63 |
+| Round to tens, half-even | 21.64 | 25.25 |
+| Running sum then divide by 3 | 48.17 | 36.85 |
+
+The expanded [average report](../research/benchmarks/decimal-average.json) uses
+the same native AOT method and database versions. All cases consume 10000 rows;
+the ordinary average returns one row, while the running average returns 10000:
+
+| Operation | Returned rows | SQLite ms | PostgreSQL ms |
+| --- | ---: | ---: | ---: |
+| Average, scale 2, half-even | 1 | 8.78 | 2.74 |
+| Running average, scale 2, half-even | 10000 | 29.12 | 47.25 |
+
+Both reports retain individual samples; the expanded script also reruns the
+read/divide/round controls. The earlier division table above refers to its original
+report, rather than mixing results from separate runs.
+
+These are single-client end-to-end samples, including query compilation, database
+work, row transport and Decimal decoding. They are not latency percentiles,
+concurrency measurements, or estimates for large coefficients/high scales.
+No other ORM test/build workload ran during measurement.
+
+```sh
+dart build cli --target=tool/benchmark_decimal.dart --output=/tmp/orm-decimal-benchmark
+/tmp/orm-decimal-benchmark/bundle/bin/benchmark_decimal > /tmp/decimal-division.json
+```
+
+Set `ORM_TEST_POSTGRES` to an accessible disposable local PostgreSQL URL to include
+PostgreSQL. The script disables TLS for that local connection, creates a uniquely
+named schema and drops its schema afterward; the account needs schema-creation
+permission. Without the variable it measures SQLite only. Run separately from
+tests and builds. Compilation happens before timing.
diff --git a/docs/defaults.md b/docs/defaults.md
new file mode 100644
index 00000000..23f2ce9d
--- /dev/null
+++ b/docs/defaults.md
@@ -0,0 +1,82 @@
+# Client values and database defaults
+
+Use `@ClientDefault(factory)` when Dart should generate an omitted insert value.
+Keep `@Default.sql(...)` for values generated by the database.
+
+```dart
+String initialLabel() => 'draft';
+
+typedef Entry = ({
+ @Id.generated() int id,
+ @ClientDefault(DateTime.now) DateTime createdAt,
+ @ClientDefault(initialLabel) @Default.sql("'server'") String label,
+});
+final entries = entity();
+
+final entry = await db.entries.create(); // Dart timestamp/label; database id.
+await db.entries.create(label: .set('manual'));
+await db.entries.create(label: .defaultValue()); // SQL supplies "server".
+```
+
+Factories can be public top-level functions, static methods, constructors or
+public const function references. They must accept a call without required
+arguments and return a type compatible with the field, including domain types
+and nullability. Optional arguments keep their Dart defaults. Instantiate generic
+functions explicitly, for example `@ClientDefault(empty)`. Factory results
+are not awaited: an async `Future` is not a value for a `String` field.
+Generation reads the reference and type without calling it.
+
+## Creation and updates
+
+Generated creation parameters with client defaults use `Change`, just like
+fields with SQL defaults:
+
+| Creation input | Behavior |
+| --- | --- |
+| Omitted or `.keep()` | Generate the client value if declared; otherwise omit the SQL column |
+| `.set(value)` | Use the explicit value without calling that column's factory |
+| `.set(null)` on a nullable field | Store SQL NULL without calling the factory |
+| `.defaultValue()` | Use the database default or identity without calling the factory |
+
+When both defaults exist, omission chooses the client value. `.defaultValue()`
+requires a database default or identity; it does not rerun the client factory.
+A nullable factory returning null stores NULL even if the database has another
+default. Patches and conflict updates keep omitted fields unchanged. SQLite's
+existing restriction on UPDATE SET DEFAULT still applies.
+
+`create`, `createRow`, `insert` and `insertMany` share this behavior. Factories run
+once per omitted column per input row while constructing an insert. Batch values
+are prepared in input order. Compilation, conflict-clause construction and repeated
+execution of that prepared mutation retain those values. Construct a fresh insert
+when fresh values are needed. An INSERT prepares defaults even if ON CONFLICT
+later skips or updates the row; only explicit conflict assignments change stored
+values. Raw `db.execute` SQL bypasses client factories.
+
+Factory errors propagate before that INSERT is sent, but earlier factories may
+already have run. Rollback does not reverse Dart side effects or return consumed
+identifiers. Rebuilding an insert inside a transaction retry calls its factories
+again. Keep factories short; external effects need their own idempotency handling.
+They run in the caller's Dart isolate, including with background SQLite or a
+browser worker. Tables cache their default-bearing columns; tables without any
+client defaults use the direct insertion path.
+
+## Physical schema
+
+`Column.clientDefault` is runtime metadata. It adds no database DEFAULT and is
+absent from saved snapshots, catalog imports and migration checksums. Changing only
+a client factory produces no DDL. A required column with only a client default
+still needs an explicit value from raw-SQL writers.
+
+Adding a non-null column with only a client factory still needs a database default
+or an explicit backfill for existing rows. Migrations never run the client factory
+to populate historical data.
+
+A database identity may also have a client factory. Omission inserts the client
+ID explicitly; `.defaultValue()` asks the database to generate one. PostgreSQL
+does not advance its identity sequence for an explicit ID; SQLite rowid allocation
+considers existing rowids. Coordinate uniqueness when mixing these sources.
+
+`DateTime.now` is application time encoded by the UTC instant codec, not SQL
+CURRENT_TIMESTAMP. Ordinary Dart constructor defaults do not declare database
+defaults. Use [computed columns](computed.md) for expressions the database
+recomputes when their source values change.
diff --git a/docs/execution.md b/docs/execution.md
new file mode 100644
index 00000000..8c0688fa
--- /dev/null
+++ b/docs/execution.md
@@ -0,0 +1,359 @@
+# Streaming and execution
+
+`get()` materializes a complete result. `stream()` keeps a database cursor open
+and fetches the next batch when the consumer requests more rows:
+
+```dart
+await for (final user in db.users
+ .orderBy((u) => [u.id.asc()])
+ .stream(batchSize: 128)) {
+ await exportUser(user);
+}
+```
+
+`await for` pauses while its body awaits. With `listen`, pause/resume the
+subscription yourself; an asynchronous `onData` callback does not create demand
+control. `toList()` deliberately accumulates the whole stream in the consumer.
+
+The default batch size is 128. SQLite advances a native prepared cursor in its
+background isolate. PostgreSQL declares a server cursor and issues bounded
+`FETCH` statements. Neither adapter first materializes all root rows in Dart.
+The SQL plan can still sort or aggregate before it returns its first row.
+
+Relations are loaded once per root batch on the same connection, including
+nested selections and per-parent limits. Memory includes the selected related
+rows: use relation `take()` when a parent can have a large collection. Root
+batch size alone does not bound that collection.
+
+A stream holds one connection until completion or cancellation. Outside an
+explicit transaction it opens a read transaction, committing after normal
+exhaustion and rolling back on early exit or failure. PostgreSQL uses a
+non-holdable, forward-only cursor. For a consistent snapshot across root and
+relationship queries, stream inside a transaction with the required isolation:
+
+```dart
+await db.transaction((tx) async {
+ await for (final row in tx.users.stream()) {
+ await consume(row);
+ }
+}, options: const PostgresTransaction(
+ isolation: Isolation.repeatableRead,
+ readOnly: true,
+));
+```
+
+Finish/cancel subscriptions inside a transaction or leased session callback.
+An escaping active stream is stopped and the callback fails with
+`TRANSACTION.UNAWAITED` or `SESSION.UNAWAITED`. `Database.close()` also stops
+active cursors before releasing its driver. A leased connection executes one
+statement at a time; overlapping statements fail with `SESSION.BUSY`.
+Concurrent `close()` callers all await the same drain and driver shutdown.
+
+## Connection acquisition
+
+```dart
+final options = ExecutionOptions(
+ acquireTimeout: const Duration(seconds: 1),
+ timeout: const Duration(seconds: 5),
+ cancellation: token,
+);
+final rows = await db.users.select((u) => u.email).get(options: options);
+
+await db.transaction((tx) async {
+ await tx.users.create(email: 'within-a-lease@example.com');
+}, acquire: const AcquisitionOptions(timeout: Duration(seconds: 2)));
+
+await db.session((session) async {
+ // This session already owns its connection.
+}, acquire: AcquisitionOptions(
+ timeout: const Duration(seconds: 2),
+ cancellation: acquisitionToken,
+));
+```
+
+`ExecutionOptions.acquireTimeout` spans waiting for the driver to supply a
+connection, including connection establishment and initialization. It ends before
+SQL starts. The same query cancellation token covers both waiting and statement
+execution. Stream and watch options propagate this acquisition bound; batch
+inserts apply it before opening their transaction. An existing leased session
+needs no further acquisition.
+
+`AcquisitionOptions` is the corresponding session/transaction entry setting.
+Its cancellation token affects acquisition only: after the callback begins it
+does not interrupt that callback or its statements. It is not a transaction
+execution deadline. Non-positive timeouts and already-cancelled requests are
+rejected before queuing.
+
+A [Dart Future timeout](https://api.dart.dev/dart-async/Future/timeout.html) does
+not cancel its source computation. Expired acquisitions report `CONNECTION.TIMEOUT`; requested cancellation reports
+`OPERATION.CANCELLED`. The ORM does not merely abandon a Future: a late driver
+lease is returned without entering the query, mutation or transaction callback.
+A monotonic clock also checks the deadline at entry, so a delayed Dart Timer
+cannot allow expired work to start. The underlying pool can retain its reservation
+until it grants a lease or fails; the ORM does not pretend that it can remove an
+entry from a driver queue that exposes no removal API. `Database.close()` waits
+for these reservations to drain. A caller holding a session must still release it.
+
+PostgreSQL has separate driver settings:
+
+| Setting | Default | Scope |
+| --- | --- | --- |
+| `PostgresOptions.connectTimeout` | 10 seconds | Establishing a new connection |
+| `PostgresOptions.poolTimeout` | 30 seconds | Native driver's pool queue waits |
+| `PostgresOptions.queryTimeout` | 30 seconds | Each SQL statement |
+| `ExecutionOptions.acquireTimeout` | unset | Entire acquisition for this operation |
+
+The per-operation bound can shorten acquisition; it does not enlarge the native
+pool limit. Borrowed pools retain their owner's connection and queue settings.
+Driver timeouts before callback entry are classified as `CONNECTION.TIMEOUT`;
+a `TimeoutException` thrown by application code after entry is preserved.
+SQLite's `busyTimeout` controls database lock waits, not its ORM lease queue.
+Neither backend's connection settings substitute for a total transaction deadline.
+
+## Cancellation and statement deadlines
+
+```dart
+final token = CancellationToken();
+final options = ExecutionOptions(
+ cancellation: token,
+ timeout: const Duration(seconds: 5),
+);
+final pending = db.users.where((u) => u.email.eq(email)).get(options: options);
+// Another event can call token.cancel().
+final users = await pending;
+```
+
+Options are accepted by query `get/first/single/count/exists/stream`, mutation
+`execute`, returning `get/single/first`, `createRow`, batch execution/returning,
+and `Database.execute`. They propagate into relation loads and batch chunks.
+Generated named `create/patch` shortcuts currently use default execution
+options; use the underlying insert/update builder for explicit options.
+
+`timeout` applies to each SQL statement or cursor fetch. It excludes time spent
+waiting for a connection and consuming already fetched rows. It is not a total
+transaction deadline. Use `acquireTimeout` for the separate acquisition phase.
+`capabilities.statementTimeout` reports statement deadline support, while
+`capabilities.cancellation` reports token-based interruption. MySQL/MariaDB support
+the former by discarding their connection; they do not support the latter.
+Cancellation while acquiring a connection now completes promptly and prevents
+the SQL callback from ever entering, including when the driver grants a lease
+later. Cancellation of an executing statement still awaits database cleanup.
+
+A token is a sticky request, not proof that a write was rolled back. Always await
+the operation's result: a completed statement may win the cancellation race and
+return success. `OPERATION.TIMEOUT` reports an expired statement deadline; it is
+not proof of rollback. MySQL/MariaDB discard the socket and close the driver, so a
+write's outcome can remain unknown and further work needs a newly opened driver.
+Connection loss and uncertain commits likewise require checking the outcome.
+Writes are retried only inside an explicitly opted-in
+transaction, subject to the confirmed-rollback rules below.
+
+SQLite uses `sqlite3_interrupt` from the exact native asset backing the open
+database. `capabilities.cancellation` is false if that build does not export the
+symbol. Such builds reject cancellation/deadlines instead of merely abandoning
+a running future. In particular, the default Linux build of `sqlite3` 3.6.0 hides
+that symbol: statement cancellation, execution deadlines and bounded transaction
+retries are unavailable there. Ordinary reads, writes, transactions and streaming
+remain available. Native macOS JIT and AOT interruption have been verified.
+The native acceptance program checks interruption when available and explicit
+capability rejection otherwise:
+
+```sh
+dart build cli --target=test/support/native_execution.dart --output=/tmp/orm-native-check
+/tmp/orm-native-check/bundle/bin/native_execution
+```
+
+Distribute the complete `bundle` directory, including its native libraries.
+`dart compile exe` alone does not bundle dependency build-hook assets; see
+[Dart CLI builds](https://dart.dev/tools/dart-build).
+
+PostgreSQL opens a separate control connection only when cancellation is
+requested and calls `pg_cancel_backend` for the leased backend. It waits for
+control cleanup before permitting another statement. This may temporarily use
+one connection beyond the pool limit. The control role must be allowed to cancel
+the original backend; the default uses the same connection credentials.
+
+The deadline also covers the first backend PID lookup. Cancellation before that
+lookup completes discards the connection without sending the application SQL.
+Successful lookups are cached for reuse of the same physical connection.
+
+Owned PostgreSQL drivers default to a 30-second statement deadline, configurable
+with `PostgresOptions.queryTimeout`. `PostgresDriver.borrow` needs a
+`cancellationConnection` factory for cancellation or deadlines, and accepts its
+own optional `queryTimeout`. The borrowed pool's statement timeout is not used:
+the ORM controls cancellation completion itself. Closing a borrowed ORM driver
+does not close the caller's pool.
+
+An interrupted statement marks an explicit transaction failed even if its error
+is caught. Cancellation between batch chunks also fails the transaction, so
+catching that error cannot commit earlier chunks. Use a savepoint for recoverable work. Cancelling a stream while a
+PostgreSQL fetch is executing can abort that transaction; ending a stream between
+fetches just closes its cursor.
+
+`onQuery` reports `execute`, `cursorOpen`, `cursorFetch` and `cursorClose` events.
+Fetch events include actual batch row counts; they carry the original query SQL
+for attribution. Parameters are counted but their values are not recorded.
+
+Optional `onAcquire` and `onDecode` callbacks separately report lease acquisition
+and synchronous ORM result processing. See [plans and observations](observability.md)
+for their scopes, inheritance and limits, and non-executing `query.inspect()`.
+
+
+## Transaction deadlines and failure outcomes
+
+```dart
+final cancel = CancellationToken();
+await db.transaction((tx) async {
+ await tx.users.create(email: 'one@example.com');
+ await tx.savepoint((child) async {
+ await child.users.create(email: 'two@example.com');
+ });
+},
+ acquire: const AcquisitionOptions(timeout: Duration(seconds: 1)),
+ timeout: const Duration(seconds: 5),
+ cancellation: cancel,
+);
+```
+
+`transaction(timeout: ...)` starts after acquiring its connection, immediately
+before BEGIN. It covers BEGIN, application callback time, all statements and
+savepoints, cursor consumption, and COMMIT. It does not restart for each query or
+savepoint. A monotonic check prevents new SQL or COMMIT after a CPU-bound callback
+has exceeded the deadline even when its Timer could not run promptly. The
+transaction cancellation token also cancels acquisition; `acquire.cancellation`
+continues to apply only to acquisition.
+
+Expiration rejects new operations, cancels active SQL and cursors, drains pending
+work, and rolls back using the underlying connection without the expired token.
+The outer Future completes after this cleanup. Cleanup can exceed the requested
+duration: stopping a statement, waiting for SQLite's busy handler, and confirming
+rollback take time. A driver without actual statement cancellation rejects these
+options before starting the transaction.
+
+Dart cannot forcibly stop an arbitrary asynchronous callback or interrupt Dart
+code currently monopolizing its isolate. A callback waiting on another Future
+may resume later; its expired database view rejects further operations. Its late
+errors are observed. External effects performed by callback code are not rolled
+back by the ORM. Use transaction/outbox patterns for effects that must follow
+committed data.
+
+Successful COMMIT acknowledgement wins a cancellation race. Failure outcomes are
+explicit:
+
+| Outcome | Error |
+| --- | --- |
+| Transaction deadline expires before confirmed commit | `TRANSACTION.TIMEOUT` |
+| Transaction cancellation during execution | `TRANSACTION.CANCELLED` |
+| Cancellation while still acquiring | `OPERATION.CANCELLED` |
+| Shorter statement timeout | `OPERATION.TIMEOUT` |
+| Database has already ended the transaction | `TRANSACTION.ENDED` for further calls; the enclosing transaction fails |
+| Rollback cannot be confirmed | `TRANSACTION.ROLLBACK`; the connection is discarded |
+| COMMIT outcome cannot be established | `TRANSACTION.COMMIT`; never assume callback replay is safe |
+| Server explicitly rejects COMMIT | Original classified `SqlFailure`, or the elapsed transaction deadline with that failure as its cause |
+
+PostgreSQL can replace a discarded physical connection from its pool. SQLite
+uses one worker connection; discarding it requires reopening the database, and
+an in-memory database cannot preserve its contents across that reopen.
+
+`SqlFailure` exposes conservative `retryTransaction`, `retryCommit` and `commitRejected`
+classification. Native PostgreSQL errors use `PostgresFailure`, retaining the
+SQLSTATE in `code` and the original `package:postgres` exception in `cause`.
+SQLite retains `SqliteFailure.code`, `extendedCode` and `message`.
+
+| Database error | Possible transaction retry after confirmed rollback | Known COMMIT rejection |
+| --- | --- | --- |
+| PostgreSQL `40001` or `40P01` | Yes | Yes |
+| PostgreSQL integrity constraints, SQLSTATE class `23` | No | Yes |
+| PostgreSQL `40003` | No | No |
+| SQLite `BUSY`, including extended busy codes | Yes | Yes |
+| SQLite constraint errors | No | Yes |
+| Other errors | No automatic eligibility | Conservatively unknown |
+
+These flags do not enable retries by themselves. Without `retry:`, the ORM makes
+one attempt, rolls back a rejected transaction and returns its failure.
+PostgreSQL serialization failures require repeating the whole transaction logic,
+including reads and application decisions.
+[PostgreSQL retry guidance](https://www.postgresql.org/docs/current/mvcc-serialization-failure-handling.html)
+and the [SQLSTATE catalog](https://www.postgresql.org/docs/current/errcodes-appendix.html)
+explain these distinctions.
+
+SQLite reports actual autocommit state from the worker after every completed
+request, including errors. If an interrupt or `OR ROLLBACK` has already rolled
+back the whole transaction, the ORM skips a redundant ROLLBACK. A vanished
+savepoint marks its parent failed and prevents subsequent writes from silently
+running in autocommit mode. Healthy SQLite connections remain usable. PostgreSQL's
+current Dart driver does not expose transaction status publicly, so its adapter
+reports an unknown state and confirms cleanup with ROLLBACK.
+[SQLite autocommit status](https://www.sqlite.org/c3ref/get_autocommit.html)
+and [transaction error handling](https://www.sqlite.org/lang_transaction.html)
+describe why statement errors alone cannot establish SQLite transaction state.
+
+
+## Explicit bounded retries
+
+```dart
+final result = await db.transaction((tx) async {
+ final user = await tx.users.byId(userId).single();
+ await tx.users.where((u) => u.id.eq(userId))
+ .update((u) => [u.nickname.set(user.email)]).execute();
+ return user.email;
+},
+ retry: const TransactionRetry(
+ maxAttempts: 3,
+ timeout: Duration(seconds: 5),
+ delay: Duration(milliseconds: 10),
+ maxDelay: Duration(milliseconds: 250),
+ ),
+);
+```
+
+The callback must be safe to repeat after database rollback. Each callback attempt
+receives a fresh transaction view and re-executes its reads and decisions. The
+previous view closes before another attempt can enter. Application errors,
+constraint violations, cancelled statements and caught transaction failures do
+not trigger replay. A failed attempt's write notifications are discarded; only a
+confirmed commit publishes them. Unknown COMMIT outcomes and unconfirmed rollback
+always prohibit replay, even when a retry policy is supplied.
+
+Defaults are three attempts, a 30-second total budget, a 10-millisecond initial
+backoff and a 250-millisecond cap. Backoff grows exponentially, with jitter between
+approximately half and all of the current delay. Setting `delay: Duration.zero`
+disables backoff. The initial attempt consumes one slot; **each callback replay or
+commit-only retry consumes one additional slot from the same `maxAttempts`**.
+For example, with three slots, one callback replay leaves room for only one
+commit-only retry. Attempts are finite even when repeated failures happen quickly.
+Exhausting slots returns the final database failure; expiry reports
+`TRANSACTION.TIMEOUT`. Cancellation interrupts backoff and reports the transaction
+cancellation error without starting another attempt.
+
+SQLite COMMIT returning BUSY is retried in place only if the adapter confirms the
+same transaction is still active. The successful callback is not re-entered, so
+its in-memory result is retained. A SQLite busy snapshot error during a statement
+instead requires confirmed rollback and replay from BEGIN. PostgreSQL serialization
+failures and deadlocks also require whole-transaction replay. The current PostgreSQL
+adapter never retries COMMIT in place.
+
+`TransactionRetry.timeout` starts at the transaction call and includes acquisition,
+all attempts, callback time, SQL and backoff. `transaction(timeout: ...)` still
+starts after acquisition and spans all attempts; the shorter remaining budget wins.
+A shorter explicit acquisition timeout reports `CONNECTION.TIMEOUT`, as do native
+pool/connection failures. An ORM acquisition timer limited by the retry budget
+reports `TRANSACTION.TIMEOUT`. These error classes are tied to the source of expiry,
+not inferred from timing after the error. Native cancellation support is required.
+The cleanup and confirmed-COMMIT rules above also apply to retries.
+
+One connection remains leased for the bounded attempt series, including backoff.
+This preserves session state and avoids reacquisition on each retry, but holds a
+pool slot while waiting. Keep budgets short under contention. The ORM does not
+reconnect and replay after a transport failure, and external callback effects are
+not rolled back. This API makes no exactly-once guarantee for such effects.
+
+The real-database retry checks include PostgreSQL serialization/deadlock conflicts,
+SQLite WAL snapshot conflicts and DELETE-journal COMMIT lock contention. Additional
+driver-injected failures exercise rollback, budgets and lost acknowledgements.
+Native SQLite retry acceptance also runs without the JIT/test runner:
+
+```sh
+dart build cli --target=test/support/native_retry.dart --output=/tmp/orm-native-retry
+/tmp/orm-native-retry/bundle/bin/native_retry
+```
diff --git a/docs/flutter.md b/docs/flutter.md
new file mode 100644
index 00000000..057e5d5e
--- /dev/null
+++ b/docs/flutter.md
@@ -0,0 +1,59 @@
+# Native Flutter
+
+The standalone runtime has a fresh [Android acceptance capture](../research/validation/standalone-flutter.json)
+at `7a54553`: 4/17/11 checks pass across installation, AOT upgrade and process
+restart. See the [current validation record](../research/validation/standalone-redesign.md).
+The detailed historical capture below remains tied to its original revision.
+
+[`example/flutter`](../example/flutter/README.md) is an actual Android application
+using generated ORM APIs and `SqliteOptions.file` in the app's private files
+directory. SQLite runs in the native driver's worker isolate. The small Android
+method channel supplies the directory, launch phase, API level and process ID;
+all database operations and migration checks run in Dart through the public ORM.
+
+The current example statically imports fixed Dart migrations and their recorded
+fingerprints. Migration JSON assets and runtime asset loading have been removed.
+The current APK capture verifies this workflow at source `85c4e42`.
+
+The [captured report](../research/validation/flutter.json) records Flutter 3.47.4
+stable, Dart 3.13.3 and SQLite 3.53.4 on an Android API 35 arm64 emulator. It includes
+the exact framework/engine revisions, APK hashes, source hashes and device build.
+
+| Installed application | Checks | Verified behavior |
+| --- | --- | --- |
+| Version code 1, debug APK | 4 | Empty database, initial migration, generated transactional inserts, close and read-only reopen |
+| Version code 2, release AOT APK, `adb install -r` | 17 | Existing file/history, only the pending migration, live catalog, original values/microseconds, new default, generated relations, committed watch refresh, rollback without persistence/notification, typed patch, worker progress, native cancellation and reuse, application version and read-only reopen |
+| Same version 2 APK after force-stop/relaunch | 11 | New process, retained database/rows/relations/history, no migration replay, initial watch, compatibility and read-only reopen |
+
+These are 32 assertions across three phases, not 32 independent platform scenarios.
+The host independently checks installed APK version codes, distinct live process
+IDs, an unchanged database path and identical final rows/history after restart.
+The old physical `body` column remains in place when Dart exposes it as `text`.
+The upgrade adds a defaulted `done` column and a comments table without dropping
+or rebuilding the existing notes table.
+
+During the final captured release run, summing a recursive sequence of two million
+integers took 335,844 microseconds. The main isolate's 16 ms timer advanced 20
+times and its Flutter animation listener advanced 12 times during that awaited SQL
+operation. The report's `flutterFrames` field counts those animation frame
+callbacks; it is not a raster timing or delivered-FPS measurement. This establishes
+that database work does not occupy the UI isolate for the entire query. It does
+not establish a frame-rate target or physical-device performance.
+
+
+
+Build and run commands are in the [example instructions](../example/flutter/README.md).
+`tool/test_flutter.dart` requires a dedicated emulator and refuses an already
+installed acceptance application. Both APKs use the example's debug signing key
+to permit a real upgrade with retained data. Reports travel through bounded log
+chunks; Android's Flutter log sink truncated larger chunks during development,
+so the application uses 700-character payloads. The host rejects incomplete or
+conflicting chunks and waits for the activity transition before its screenshot.
+
+This verifies Android arm64 on the recorded emulator. Physical devices, iOS and
+macOS Flutter need their own acceptance runs. Process force-stop/relaunch does not
+simulate sudden power loss. Watch refreshes cover writes made through the same
+database instance; external writes still need [explicit invalidation](watch.md).
+The [native Dart migration regression](../research/validation/dart-migrations.json)
+and 19 scenarios in each Chrome JS/WASM run are separate evidence. The compiled
+APK histories have fixed fingerprints and need no schema or migration JSON assets.
diff --git a/docs/generation.md b/docs/generation.md
new file mode 100644
index 00000000..ca0651dd
--- /dev/null
+++ b/docs/generation.md
@@ -0,0 +1,242 @@
+# Generation and incremental builds
+
+The ORM supports a standalone CLI and the standard
+[Dart build_runner workflow](https://dart.dev/tools/build_runner). Both use the
+same schema validation, emission and in-process formatter. Generation reads
+declarations and produces source/metadata; it does not connect to or migrate a
+database.
+
+Generated clients export their nominal model classes or explicit Record aliases
+and an immutable `appSchema`; entity
+declaration values remain in the source library. Import the generated client and
+the chosen driver in application code. Programmatic generation is in
+`generate.dart`; build_runner factories are exported only by `builder.dart`.
+See [API boundaries](api.md).
+
+Generation validates declaration structure and generated symbol names. Database
+member collisions such as an entity called `close` fail here; keep the physical
+name with `table:` when renaming its Dart declaration. Database-specific computed
+and identifier restrictions are checked when selecting the migration engine.
+
+## Standalone command
+
+```sh
+dart run orm init --database sqlite
+dart run orm generate
+# Or select a source explicitly:
+dart run orm generate lib/schema.dart
+```
+
+Initialization creates typed `orm.config.dart`, a model and static migration
+history without connecting. The path-free command uses `OrmConfig.schema` (or
+`lib/schema.dart` when no config exists). See [project CLI](cli.md).
+
+This writes `lib/schema.orm.dart` and `lib/schema.snapshot.dart`. The latter is the
+physical schema snapshot used by migration tools. It is a standalone Dart library
+with no application imports. An explicit `database.dart` output gets an adjacent
+`database.snapshot.dart`. For an explicitly chosen
+output path:
+
+```sh
+dart run orm generate lib/schema.dart lib/generated/database.dart
+```
+
+The CLI checks source errors and resolves imports using the project's package
+configuration. Use it when a single explicit generation step suits the project.
+
+## build_runner
+
+Schema libraries use Dart language version 3.13. Set the application's SDK
+constraint to `'>=3.13.0 <4.0.0'` when adopting the declaration syntax.
+
+Add `build_runner` as a development dependency in the application using `orm`:
+
+```sh
+dart pub add dev:build_runner
+```
+
+Select the schema roots in the application's `build.yaml`:
+
+```yaml
+targets:
+ $default:
+ builders:
+ orm:orm:
+ enabled: true
+ generate_for:
+ - lib/schema.dart
+```
+
+Then run a build or keep a watcher open:
+
+```sh
+dart run build_runner build
+dart run build_runner watch
+```
+
+The builder is opt-in and uses the explicit `generate_for` list. Select schema
+libraries containing `entity()` declarations, rather than every Dart
+file or a `part of` file. Additional roots produce their own clients and snapshots
+next to their input files. Import generated clients with prefixes if their
+declaration names overlap.
+
+The output of `lib/schema.dart` is always `lib/schema.orm.dart` and
+`lib/schema.snapshot.dart`. There are no ORM-specific builder options. Use the CLI's
+output argument for other locations. `build_runner` owns its build cache and output
+cleanup; do not manually edit that cache or generated source.
+
+## What triggers regeneration
+
+The builder resolves source through `BuildStep.resolver` and writes through
+`BuildStep.writeAsString`. It shares build_runner's analysis infrastructure and
+asset dependency tracking. No independent filesystem analyzer is launched for
+each build step. Schema imports, exports and parts reachable during resolution
+are tracked; this includes imported enums, const defaults and custom codecs.
+Types generated by an earlier builder can also be resolved.
+
+Changes to a schema field regenerate its client and snapshot. Imported metadata
+changes also regenerate them. The process test verifies that an unrelated source
+file edit does not start a build or touch the generated client. Deleting a schema
+root removes its generated outputs; recreating it regenerates them.
+
+A new `build_runner build` process with unchanged inputs reports zero outputs.
+An unrelated edit in watch mode can remain completely silent, with no completion
+event because no build was needed. Standard build configuration is described in
+the [build_runner documentation](https://pub.dev/packages/build_runner).
+
+## Errors and generated output
+
+Both entry points validate the schema's Dart semantic errors before emission.
+The builder also rejects non-library roots, unknown codec mappings and duplicate
+enum storage labels. Formatting of client and snapshot source finish before it
+writes either output. A failed build reports an error; repairing the input lets
+the same watcher generate again.
+
+Application encoders and decoders are not executed. Const annotations provide
+the metadata; source static types preserve domain IDs even when constant
+evaluation erases an extension type's representation.
+
+Generated source stays reviewable and can be committed with the application.
+Schema snapshot changes are migration inputs, not permission to apply DDL
+automatically. Follow the [migration workflow](migrations.md) to review and apply
+database changes.
+
+## Measurements and verification
+
+Run the reproducible consumer-project benchmark from the ORM repository:
+
+```sh
+dart run tool/benchmark_generation.dart
+```
+
+It creates disposable projects containing 10, 100 and 1000 four-field record
+models. For each, it measures the first build, an unchanged build, watcher startup,
+a field edit, an imported metadata edit and static analysis. It also verifies
+that an unrelated edit leaves the watcher idle and output timestamps unchanged.
+Its [JSON report](../research/benchmarks/generation.json) records SDK/package
+versions, hardware, source/output sizes and measurement conditions.
+
+These are one-sample development-machine observations. Dependency download is
+excluded, shared SDK/pub/native caches are warm, and process/watch startup costs
+are included where applicable. They are not p50/p95 results or IDE completion
+measurements. The first build includes build_runner's builder compilation. Run
+the benchmark independently of test suites or other builds, with the generator
+source fixed for the entire run.
+
+Historical measurements before the Dart snapshot workflow, recorded on Apple M3 Max with Dart 3.13.3 and build_runner 2.16.1 (seconds):
+
+| Models | First build | Unchanged build | Watch field edit | Watch import edit | Analyze |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| 10 | 16.20 | 0.57 | 0.52 | 0.40 | 0.48 |
+| 100 | 16.26 | 0.57 | 0.65 | 0.66 | 0.50 |
+| 1000 | 17.96 | 0.58 | 2.17 | 2.22 | 3.48 |
+
+All three unchanged builds wrote zero outputs. Unrelated edits stayed idle during
+the one-second observation window. The 1000-model client contains 2,343,598 bytes
+after the edit; its result shape is a single schema library with four fields per
+model and one added field on the first model.
+
+Tests compare builder and CLI output, validate in-memory assets and prior-builder
+outputs, and run real build/watch processes for dependency changes, failure
+recovery and output cleanup. Static analysis of the generated consumer project
+is part of that process test.
+
+## Editor completion, diagnostics and rename
+
+Run `dart run tool/benchmark_editor.dart` to exercise the installed Dart Analysis
+Server over stdio LSP in disposable consumer projects. `--smoke` checks ten models
+with two warm samples and writes only under `.dart_tool/`. The full run writes
+[`editor.json`](../research/benchmarks/editor.json), including the runtime commit,
+harness hashes, raw samples, diagnostic ranges, rename edits and resulting source.
+The protocol is documented by the [Dart 3.13.3 SDK](https://github.com/dart-lang/sdk/blob/3.13.3/pkg/analysis_server/tool/lsp_spec/README.md).
+
+On Apple M3 Max / Dart 3.13.3, warm completion p50 / p95 in **milliseconds**:
+
+| Models | Table entries | Schema Record fields | Query fields | Create arguments | Projected Record fields |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| 10 | 0.809 / 1.117 | 0.439 / 0.511 | 0.484 / 1.126 | 0.238 / 0.293 | 0.518 / 0.590 |
+| 100 | 1.497 / 2.812 | 0.428 / 0.492 | 0.484 / 0.559 | 0.250 / 0.315 | 0.568 / 0.600 |
+| 1000 | 11.572 / 17.094 | 0.705 / 0.788 | 0.780 / 0.850 | 0.226 / 0.307 | 1.330 / 2.863 |
+
+Each cell uses twenty unchanged-document requests after two unrecorded warmups;
+quantiles use nearest rank. These numbers include client transport/JSON handling
+but exclude editor UI/plugin rendering. Dependency installation is offline and
+outside timing; shared SDK/pub/OS caches are not cleared. They are local protocol
+measurements, not a ranking against another ORM or declaration frontend.
+
+Warm completion excludes opening/editing and analysis readiness. Initial server
+startup plus project analysis took 0.311 / 0.487 / 3.405 seconds respectively. At
+1000 models, the query-field probe waited 128.488 ms for a diagnostic after opening
+the incomplete expression, then its first completion took 4.109 ms. The schema
+field probe waited 165.844 ms. The report separates these observations from warm
+samples; they must not be described as sub-millisecond edit-to-suggestion latency.
+
+All fifteen probe shapes returned their required labels. A two-field named Record
+projection offered `id` and `title` but did not offer the unselected `score` or
+`status`. Each scale also checked four deliberate type errors: create input,
+predicate value, scalar result assignment and access to an unselected field. Each
+diagnostic must match both its code and the current token's exact source range.
+Changes are serialized because this SDK omits diagnostic document versions. A
+fresh diagnostic clears the repaired client error. A separate CLI analysis checks
+the final edited consumer, rather than treating an absent notification as success.
+
+The language-symbol rename results are the same at all three scales:
+
+| Declaration | Observed result |
+| --- | --- |
+| Named Record field | Both prepare and rename return `null`; unavailable |
+| Primary-constructor class field | Declaration and typed member reference updated |
+| Class-based table field | Dart field and typed reference updated; SQL column string retained |
+| Record typedef name | Declaration and both type references updated; separate Record alias retained |
+
+These are language-symbol probes. They do not compare three ORM authoring
+frontends generating identical APIs. Renames use a fresh server after the error
+probes. A subsequent [recovery capture](../research/validation/editor-recovery.json)
+reproduces the same-session failure using `dart run tool/benchmark_editor.dart
+--same-session`: at ten models, five completion probes, four exact-code/range
+diagnostics and their repair finish, then `textDocument/rename` for the primary
+constructor field times out after 60 seconds. The process exits nonzero before
+attempting the larger scales; the [original log](../research/validation/editor-recovery.log)
+is retained. `--smoke` on the same harness restarts the server before rename and
+completes the class/table/alias edits plus final analysis. Server PIDs and source
+hashes are recorded. The underlying SDK/harness interaction is not diagnosed;
+this is a reproducible limitation with a checked restart path, not general IDE
+reliability or a claim that the SDK alone caused it.
+
+Record field edits therefore require reviewing declaration/selector references,
+regenerating, and repairing application references with the type checker. Do not
+edit generated files to perform a schema rename. To change only a Dart field name,
+keep its physical column explicit, for example
+`@ColumnName('name') String displayName`. A physical database rename still needs
+the reviewed [migration workflow](migrations.md).
+
+ORM selector rules are a separate diagnostic boundary: the valid Dart expression
+`rows0.index((r) => r.id + 1)` passes CLI analysis but fails generation with a
+direct-field-selector error and source offset. Stock LSP does not supply that ORM
+diagnostic. Keep generation/watch running for schema rule validation.
+
+The separate [declaration-form experiment](authoring.md) now compares Record,
+primary-constructor and table-class inputs for the same four related models.
+It checks identical generated APIs/snapshots across field edits and renames,
+stale-client type errors, schema refactor propagation and original error locations.
+Its class/table adapters are experimental tools, not supported package entrypoints.
diff --git a/docs/importing.md b/docs/importing.md
new file mode 100644
index 00000000..814ce86c
--- /dev/null
+++ b/docs/importing.md
@@ -0,0 +1,174 @@
+# Import an existing database
+
+Import reads the catalog and produces an editable nominal model declaration plus a review
+report. It does not sample rows, create migration history, change tables, or copy
+data. Generate the client and baseline the reviewed schema as separate steps.
+
+```sh
+dart run orm db import --sqlite app.sqlite --output lib/schema.dart
+# PostgreSQL alternative:
+dart run orm db import --postgres-env DATABASE_URL --database-schema public --output lib/schema.dart
+# MySQL/MariaDB alternatives:
+dart run orm db import --mysql-env DATABASE_URL --output lib/schema.dart
+dart run orm db import --mariadb-env DATABASE_URL --output lib/schema.dart
+
+# Review lib/schema.dart and lib/schema.import.json first.
+dart run orm generate lib/schema.dart
+# Add the Dart entrypoint described in migrations.md, then:
+dart run orm migration registry migrations --dialect sqlite
+dart run bin/migrate.dart create 0001_baseline
+dart run bin/migrate.dart baseline
+dart run bin/migrate.dart verify
+```
+
+Use `--dialect postgres`, `mysql` or `mariadb` for the matching server's registry.
+Configure the same database in the [Dart migration entrypoint](migrations.md). Existing database-specific defaults and objects need reviewed migrations;
+an imported declaration is not automatically a portable creation script for the
+other dialect. Baseline verifies the declared schema before recording history and
+does not execute the initial creation SQL.
+
+`--output` must name a new `.dart` file. Neither it nor the adjacent `.import.json`
+report may already exist. SQLite opens read-only and requires an existing file.
+PostgreSQL uses a read-only, repeatable-read transaction in the selected schema.
+Each invocation uses one catalog snapshot. Existing outer transactions are rejected;
+a borrowed session without an active transaction is allowed.
+
+To import one table, use `--table accounts`. For a selected related group, use
+`importSchema(db, tables: ['accounts', 'notes'])` in Dart. Without a selection,
+discovery covers SQLite main, the current PostgreSQL schema or the selected
+MySQL/MariaDB database. `db` is a raw `SqlDatabase`; use `ormDatabase.sql` for an
+ORM connection. Internal ORM history
+tables are omitted. Include the referenced tables when importing relationships;
+missing targets and temporary objects shadowing selected tables produce issues.
+
+## Declarations and reports
+
+```dart
+import 'package:orm/schema.dart';
+
+final class AccountsRow({
+ @ColumnName('id') @Id.generated() required final int id,
+ @ColumnName('email') required final String email,
+ @ColumnName('display_name') required final String? displayName,
+});
+final accounts = entity(table: 'accounts');
+final accountsUnique = accounts.unique((row) => row.email);
+```
+
+Every table and field retains an explicit physical name. Dart keywords, punctuation,
+Unicode-only names and collisions get valid names recorded in the report's
+`entities` and `fields` maps. Rename Dart symbols to match your domain while keeping
+the physical mappings. Primary/composite keys, unique constraints, simple named
+indexes and representable foreign keys become declarations. Relationships get names
+and inverse selections; rename these before generation if a domain name is clearer.
+Foreign-key actions include SET DEFAULT on supporting engines; MySQL/MariaDB
+reject it. Unsupported unsigned and binary storage must be reviewed explicitly;
+see [MySQL/MariaDB limits](mysql.md).
+
+Ordinary enforced [CHECK constraints](checks.md) become `.check(...)` declarations
+with their native names and SQL. A nonblocking `IMPORT.CHECK_SQL` note requests
+review of backend-specific expressions before deployment on another dialect.
+PostgreSQL unvalidated, unenforced and inheritance-specific checks remain unmanaged.
+
+The JSON report records the dialect, schema, name maps, and issues:
+
+- Blocking issues exclude an unsupported table or relation. CLI exit code is 2;
+ the partial draft and report are still written for review.
+- Nonblocking issues preserve descriptions of unmanaged objects, such as views,
+ triggers and specialized indexes. Exit code remains 0, but those objects still
+ need separate review and database-specific migration handling.
+- Invalid options or existing output paths use exit code 64. Existing files remain.
+
+An empty issue list is not proof of complete database equivalence. Catalog support
+and `verifySchema` cover declared facts; they do not prove that grants, extensions,
+database settings or every native object can be recreated from a Record schema.
+
+## Types and boundaries
+
+Import uses exact physical mappings. It never infers a semantic type from example
+rows or a column name.
+
+| SQLite | PostgreSQL | Draft Dart type |
+|---|---|---|
+| INTEGER | SMALLINT / INTEGER / BIGINT | int, with width metadata where needed |
+| TEXT | TEXT | String |
+| TEXT COLLATE orm_decimal_v1, optional precision CHECK | NUMERIC, NUMERIC(p,s) | Decimal, optional DecimalDigits |
+| REAL | DOUBLE PRECISION | double |
+| BLOB | BYTEA | Uint8List |
+| — | BOOLEAN | bool |
+| TEXT COLLATE orm_instant_v1 | TIMESTAMPTZ | DateTime |
+| TEXT COLLATE orm_date_v1 | DATE | LocalDate |
+| TEXT COLLATE orm_time_v1 | TIME WITHOUT TIME ZONE | LocalTime |
+| TEXT COLLATE orm_local_datetime_v1 | TIMESTAMP WITHOUT TIME ZONE | LocalDateTime |
+| — | JSONB | SqlJson with Codecs.jsonDocument |
+
+Nullability is preserved. SQLite TEXT may contain timestamps, enums, bigints or
+JSON, and INTEGER may hold application booleans. Add reviewed codecs when needed;
+the catalog does not establish those meanings. PostgreSQL NUMERIC
+imports as finite `Decimal`, never as BigInt; constrained columns retain
+`@DecimalDigits(precision, scale)`. Import does not sample values;
+existing NaN or Infinity values will fail typed decoding. SQLite requires the
+recognized column collation to establish decimal storage and recognizes only the
+emitted precision CHECK. Varchar, arrays, domains and other native types still
+need explicit support. See
+[decimal boundaries](decimals.md) before reviewing a draft.
+
+SQLite rowid integer primary keys and PostgreSQL BY DEFAULT integer primary-key
+identities get `@Id.generated()`. [Computed expressions](computed.md) become
+`@Computed.sql` with their stored/virtual mode and an `IMPORT.COMPUTED_SQL`
+portability review note. ALWAYS identities,
+non-primary identities and nullable primary keys require explicit write semantics
+and are currently blocking. Sequence defaults such as a BIGSERIAL default retain
+their catalog SQL; import does not convert them to identities or reset sequences.
+Review their dependencies before baselining.
+
+The draft targets the inspected engine. SQLite indexed virtual columns and
+PostgreSQL stored computed primary keys remain importable; the other engine's
+restrictions do not block them. Imported names that collide with Database members
+receive a distinct Dart name while retaining the physical SQL name.
+
+PostgreSQL SMALLINT/INTEGER columns and SQLite INTEGER columns with recognized
+ORM range checks retain their `@IntegerBits(16)` or `@IntegerBits(32)` declaration.
+See [integer widths](types.md#signed-integer-column-widths) for range enforcement,
+aggregation and migration behavior.
+
+SQLite import requires 3.37 or later to distinguish ordinary, virtual and shadow
+tables using [table_list](https://www.sqlite.org/pragma.html#pragma_table_list).
+Virtual tables and their backing tables are reported rather than emitted as ordinary
+models. PostgreSQL partitioned/inherited and foreign tables need explicit declarations.
+Identity modes and generated expressions have separate
+[catalog attributes](https://www.postgresql.org/docs/current/catalog-pg-attribute.html).
+
+Specialized index semantics remain in the report: partial/expression indexes and
+PostgreSQL nondefault operator classes, collation overrides, storage options and
+NULLS NOT DISTINCT. These differ from plain unique keys; see the
+[PostgreSQL index catalog](https://www.postgresql.org/docs/current/catalog-pg-index.html).
+
+PostgreSQL policy objects stay unmanaged. Their `definition` is JSON containing
+`permissive`, `roles`, `command`, `using` and `withCheck`, preserving the fields in
+[`pg_policies`](https://www.postgresql.org/docs/18/view-pg-policies.html).
+A separate `row_security` object contains the table's `enabled` and `forced`
+flags from [`pg_class`](https://www.postgresql.org/docs/18/catalog-pg-class.html).
+It is reported when either flag is set or a policy exists, including disabled
+policies. These metadata descriptions are not executable migration SQL.
+`verifySchema` and baseline return them for review without claiming that the
+Record snapshot models access-control policy. Neither operation changes those
+settings. Trigger definitions likewise remain unmanaged; import/verification
+tests exercise real triggers on both databases and verify they still execute.
+
+## Tooling API
+
+```dart
+import 'package:orm/generate.dart';
+
+final draft = await importSchema(db, tables: ['accounts', 'notes']);
+print(draft.dart);
+print(draft.toJson());
+if (draft.hasBlockingIssues) {
+ // Resolve the reported native types or relationships before baselining.
+}
+```
+
+The API returns values and writes no files. It belongs to the generator/tooling
+entry point. Generated applications continue using the normal ORM and driver
+entry points. The CLI does not automatically generate a client or apply a baseline.
diff --git a/docs/migrations.md b/docs/migrations.md
new file mode 100644
index 00000000..2e184bad
--- /dev/null
+++ b/docs/migrations.md
@@ -0,0 +1,377 @@
+# Migrations
+
+Schema snapshots, saved migrations and their registry are Dart libraries. Start
+with one typed project configuration and one fixed database engine:
+
+```sh
+dart run orm init --database sqlite
+dart run orm migrate create 0001_initial
+# Review migrations/m0001_initial.dart.
+dart run orm migrate check
+dart run orm migrate apply
+dart run orm migrate plan
+dart run orm migrate status
+dart run orm migrate verify
+dart run orm migrate inspect tasks
+```
+
+`init` also accepts `postgres`, `mysql` and `mariadb`. It generates a nominal model,
+client, physical snapshot, empty static registry and `orm.config.dart`. Existing
+files are never replaced, and initialization does not connect or execute DDL.
+See the [project CLI](cli.md) for the generated typed configuration and all options.
+
+The config is an explicit Dart entrypoint with `runOrmCli(args, config: OrmConfig(...))`.
+It statically imports its current snapshot and migration history. Connection
+factories return the independent `SqlDatabase` runtime, built with the selected
+low-level driver; migrations do not need ORM models or typed query generation.
+Server connection factories read environment variables only when connecting.
+
+Run from the project root. `migrate create` first regenerates the model's physical
+snapshot before diffing, so an edited declaration cannot use a stale snapshot.
+Other commands use their statically imported snapshot/history without changing
+source artifacts. Standalone generation remains `dart run orm generate
+lib/schema.dart`, and registry regeneration is `dart run orm migration registry
+migrations --dialect sqlite` for a new empty registry.
+
+Projects can also call the lower-level `runMigrationCli` in their own executable:
+
+```dart
+import 'package:orm/migrate_cli.dart';
+import 'package:orm/runtime.dart';
+import 'package:orm/drivers/sqlite.dart';
+import '../lib/schema.snapshot.dart';
+import '../migrations/migrations.g.dart';
+
+Future main(List args) => runMigrationCli(
+ args,
+ directory: 'migrations',
+ history: migrationHistory,
+ schema: schema,
+ connect: ({required readOnly}) async => SqlDatabase(
+ await SqliteDriver.open(readOnly
+ ? const SqliteOptions.readOnly('app.sqlite')
+ : const SqliteOptions.file('app.sqlite')),
+ ),
+);
+```
+
+Offline commands never call the connection factory. SQLite inspection requires
+an existing read-only file; `apply` can create one. Database migration/verification
+operations enforce their own transaction and locking boundaries.
+
+Each new migration is an `m.dart` file with fixed operations, an independent
+historical schema and a recorded `migrationChecksum`. The adjacent
+`migrations.g.dart` statically imports these definitions. Check both into Git.
+The current `.snapshot.dart` contains only physical database metadata and imports
+no application models, codec callbacks or Flutter libraries.
+
+`create` compares the current physical schema with the last historical snapshot
+and freezes the resulting SQL/steps in a new Dart file. It does not execute DDL.
+No-change generation writes no migration. Repeated IDs, overwritten files, stale
+registries and broken history chains are rejected when saving a new migration.
+`check` validates the compiled history, fixed fingerprints and its declared engine
+without connecting. The registry records one `migrationDialect`, including before
+the first migration. Every migration has the same explicit `dialect` and one flat
+step list. Rebuilding with `dart run orm migration registry migrations` preserves
+that target and never refreshes fingerprints. Attempting to regenerate with a
+different target fails without writing files.
+
+A connection for another engine is rejected before migration SQL, including CLI
+`status`, `verify`, `inspect` and an empty history. The connection factory itself
+runs first and may open/create a SQLite file; it must honor `readOnly`. Environment
+variables configure locations and credentials for the chosen engine, not select
+a different engine for the same history.
+
+Shared model declarations may contain per-engine expressions. Generation resolves
+only the selected engine; saved snapshots and operation tables freeze that SQL.
+Changes to another engine's override cannot change this history's plan or checksum.
+Database-specific restrictions apply only to the selected engine. Ordinary
+single-engine declarations can use `ComputedColumn(sql)` and `CheckSchema(name, sql)`.
+
+Multi-database applications own separate directories, registries and connections.
+Tests for a PostgreSQL application use PostgreSQL for migration acceptance. Switching
+to SQLite is a separate schema/data transfer and baseline operation; it does not
+translate, replay or rewrite the PostgreSQL history. Changing servers or credentials
+within the same engine preserves the history; the destination's applied hashes and
+catalog still need checking.
+
+The migration executor supports PostgreSQL 18+ and SQLite 3.35+. PostgreSQL apply,
+baseline and standalone planning read the actual server version before migration
+locks or journal writes; the SQLite driver checks its library version when opening.
+Older PostgreSQL migrations are deliberately rejected instead of attempting DDL
+whose catalog/generated-column behavior has not been verified. This does not claim
+that every older server feature is unsupported by the query driver. See the native
+[PostgreSQL ALTER TABLE](https://www.postgresql.org/docs/18/sql-altertable.html) and
+[SQLite ALTER TABLE](https://www.sqlite.org/lang_altertable.html) boundaries.
+
+Edit the latest **unpublished** migration when a generated change needs a reviewed
+backfill or manual SQL, then run `dart run orm migrate record 0002_name`.
+This explicit command updates its fingerprint while preserving the surrounding
+source. It cannot know whether a migration was deployed. Never edit or re-record
+an applied migration: database history also records checksums and rejects the
+change. Add a new migration instead. Earlier historical files remain fixed even
+when the current application model changes.
+
+Declare physical renames in the entrypoint's `renames` argument:
+
+```dart
+renames: const SchemaRenames(
+ tables: {'users': 'members'},
+ columns: {'members': {'nickname': 'display_name'}},
+),
+```
+
+Declare conversions in its `using` argument, keyed by table and column for the chosen database:
+
+```dart
+using: {
+ 'members': {'score': 'CAST(score AS TEXT)'},
+},
+```
+
+Import `package:orm/migrate.dart` for `SchemaRenames`. Renames and conversions are
+inputs to the next `create`; remove them after generating that change. Pass
+`create --allow-destructive` to generate reviewed drop steps or replace
+ordinary SQLite column values with a computed expression. Computed-to-ordinary
+SQLite changes materialize the existing result instead. Neither offline
+checking nor generation applies them.
+
+Start with [catalog import](importing.md) for an existing database, then run
+`baseline` to verify and register its final historical schema without replaying
+creation SQL. Add `--json` for machine reports (not migration artifacts). The lower-level `runMigrationCli` defaults to JSON reports. Exit code 2
+indicates catalog drift, 64 invalid CLI arguments, and 1 an execution failure.
+Dart's launcher may print build-hook progress on stderr.
+
+Application startup uses the same static history without the CLI/tooling imports:
+Here and below, `db` is a `SqlDatabase`; use `ormDatabase.sql` when starting from
+the typed ORM `Database`.
+
+```dart
+import 'migrations/migrations.g.dart';
+
+final migrations = migrationHistory.checked;
+final pending = await Migrator(db).plan(migrations);
+final appliedIds = await Migrator(db).apply(migrations);
+```
+
+For programmatic generation, `writeMigration(migration, directory: 'migrations',
+history: migrationHistory)` saves fixed Dart operations and the registry.
+`migrationSource`, `schemaSource` and `migrationHistorySource` also return Dart
+source without writing files. A saved migration contains frozen SQL and typed
+steps; it must not call `Migration.diff` against current models when it runs.
+Fingerprints cover the engine, SQL, operation data, historical schema and predecessor, while
+formatting and comments do not affect them.
+
+SQLite and PostgreSQL `apply` run a pending batch without `CheckedSql` or `Backfill` in one transaction. A failed copy, required
+column, unique constraint, or foreign key rolls back earlier steps and history
+records from that invocation. PostgreSQL uses a dedicated connection and a session advisory lock scoped to the
+current database/schema; SQLite obtains an immediate write transaction. PostgreSQL
+lock acquisition uses short `pg_try_advisory_lock` queries outside a transaction,
+with `Migrator(db, lockTimeout: ...)` defaulting to 30 seconds. Waiting does not
+hold an old SQL snapshot that could deadlock concurrent index creation.
+MySQL/MariaDB DDL commits independently and uses exact catalog preconditions,
+postconditions and durable checkpoints; see [MySQL/MariaDB migrations](mysql-migrations.md).
+
+Migration planning checks applied history and checksums. Catalog verification is
+an explicit separate operation; SQL history alone does not prove schema equality.
+
+## Deployment bundle
+
+The project entrypoint can be compiled with the SDK's native-asset-aware CLI build:
+
+```sh
+dart build cli --target orm.config.dart --output build/migration
+./build/migration/bundle/bin/orm.config migrate check
+./build/migration/bundle/bin/orm.config migrate apply
+```
+
+Deploy the complete `bundle` directory, including its native libraries. Migration
+history and snapshots are compiled into the executable; runtime `check`, `plan`,
+`apply`, `status` and `verify` do not read Dart source or migration assets. Supply
+the same environment configuration used by your connection factory. Build for the
+actual deployment OS/architecture.
+
+Use source execution during authoring. A compiled executable contains the history
+from its build and cannot discover a newly generated migration. Rebuild after
+reviewing and committing new history. The application imports `migrate.dart` and
+its registry; it does not need the generator or CLI entrypoint.
+
+## Application startup compatibility
+
+```dart
+// Default: the database must have completed the latest bundled migration.
+final version = await Migrator(db).requireVersion(migrations);
+
+// This release can run on either side of a compatible expand migration.
+await Migrator(db).requireVersion(
+ migrations,
+ minimum: '0001_initial',
+ maximum: '0002_expand',
+);
+```
+
+The range is inclusive and uses the ordered bundled history. Without bounds, the
+requirement is exactly its latest migration. With only `minimum`, the upper bound
+is the latest bundled migration; with only `maximum`, that version is required
+exactly. Bounds must name an ordered, nonempty range in the supplied history.
+The list is copied before asynchronous work begins.
+
+The check validates every applied ID/checksum in the history prefix, not just its
+last ID. An unversioned database, an older required version, a database outside the
+range, or a database newer than the bundled history reports `MIGRATION.VERSION`.
+Changed checksums or missing history entries report `MIGRATION.CHECKSUM`; corrupt
+checkpoint sequences report `MIGRATION.HISTORY`. Any recovery checkpoint for a
+migration not yet recorded as applied reports `MIGRATION.INCOMPLETE`, including
+checkpoints unknown to an older application. Complete or recover that migration
+before accepting application traffic.
+
+Call this on a root database or a leased session, outside an existing transaction.
+The check opens a short read transaction: PostgreSQL uses REPEATABLE READ READ ONLY,
+and SQLite uses a deferred read snapshot, including on an explicitly read-only
+file. It reads catalog/history/checkpoints without creating metadata or applying
+migrations. The returned `MigrationStatus` records the accepted ID and checksum.
+An existing caller transaction is rejected with `MIGRATION.SESSION` so the method
+can establish its own consistent snapshot.
+
+This is a point-in-time startup check. It does not prevent a later deployment
+from changing the database, check the actual catalog for drift, or prove that old
+application processes have stopped. Use `verifySchema` for catalog checks and
+coordinate incompatible contract migrations with application deployment. A
+rejected downgrade does not delete or rebuild tables.
+
+## Schema evolution
+
+`diff` generates operations for the history's selected engine only:
+
+- New nullable/defaulted columns use `ALTER TABLE` when SQLite permits the default.
+- SQLite changes to existing columns or keys use an explicit `RebuildTable` step.
+- Renames must be declared. Drops require `allowDestructive: true` when generating
+ the file; the resulting file makes each removal visible to review.
+- A new required column without a default needs a separate add/backfill/constrain
+ sequence. Identity changes require a manual migration.
+- Type changes require SQL conversion expressions for the selected dialect. Expressions
+ are trusted migration code and use column names after declared renames.
+
+[Computed target columns](computed.md) use their own expressions to populate old
+rows and derive values on type changes. They are excluded from rebuild copy maps;
+their addition does not require a default or application backfill. Mode conversions
+and native expression dependencies have separate documented migration limits.
+
+For long data transformations, use a reviewed [resumable backfill](backfills.md).
+It carries a historical table definition, commits bounded batches with their
+primary-key cursors, supports bounded runs, and verifies completion. Both SQLite
+and PostgreSQL support it; general `CheckedSql` autocommit operations still require
+PostgreSQL.
+
+```dart
+final change = Migration.diff(
+ '0003_score_text',
+ dialect: previousMigration.dialect,
+ from: previousSnapshot,
+ to: nextSnapshot,
+ previous: previousMigration.checksum,
+ using: {
+ 'members': {'score': 'CAST(score AS TEXT)'},
+ },
+);
+```
+
+SQLite rebuilds borrow one connection, disable foreign keys before `BEGIN`, copy
+explicit columns into a new table, replace the old table, and recreate indexes
+and triggers. They check foreign keys before commit and restore the connection's
+original foreign-key setting even on failure. Restore failure discards the
+connection. Incoming cascade relations therefore do not delete child rows during
+replacement. Existing views are retained and checked after replacement.
+
+The runner preserves unmanaged indexes and triggers whose SQL can be restored.
+Unmodeled table constraints/options (undeclared `CHECK`, collations, generated expressions,
+`STRICT`, `WITHOUT ROWID`, and similar features) require a manual migration;
+they are never silently discarded. Removing columns from a table with triggers
+also requires explicit manual handling. A new managed index cannot silently
+replace an unmanaged index of the same name.
+
+[Declared CHECK constraints](checks.md) participate in schema diffs, inspection
+and import. SQLite adds/changes/removes them through a rebuild; PostgreSQL uses
+constraint DDL. Checked renames explicitly remove and re-add the declared SQL,
+which can require two SQLite copies. Existing rows are validated before commit.
+
+Manual migrations use `Migration(id, ['SQL', ...], dialect: .sqlite)`, or
+`Migration.steps` with `ExecuteSql`, `DropTable`, and `RebuildTable` operations.
+For a custom SQLite copy-and-replace migration, an explicit `DropTable` enables
+outer foreign-key handling; preserve dependent SQL objects in the reviewed steps.
+Transaction control is owned by the runner. Use `CheckedSql` for PostgreSQL
+commands that must run outside a transaction; ordinary `ExecuteSql` rejects them.
+
+# Recoverable PostgreSQL operations
+
+```dart
+final migration = Migration.steps(
+ '0004_email_index',
+ [
+ CheckedSql.createIndex(
+ 'members',
+ const IndexSchema('members_email_lookup', ['email']),
+ ),
+ ],
+ dialect: .postgres,
+ previous: previousMigration.checksum,
+ snapshot: nextSnapshot,
+);
+```
+
+`CheckedSql.createIndex` builds a concurrent B-tree index using default column
+collations and operator classes. Its completion check compares the table, ordered
+columns, uniqueness, predicate/expression absence, index options and validity.
+A same-name object or an INVALID index is not proof of completion. PostgreSQL's
+[concurrent index documentation](https://www.postgresql.org/docs/current/sql-createindex.html#SQL-CREATEINDEX-CONCURRENTLY)
+explains its nontransactional execution and possible INVALID leftovers.
+
+Other operations use `CheckedSql(sql, readyWhen: 'SELECT ...', doneWhen: 'SELECT ...')`.
+Each condition must return exactly one boolean and accurately describe durable
+state. SQL and probes are reviewed migration code. The runner first checks
+`doneWhen`; if false, it requires `readyWhen`, executes SQL in autocommit mode,
+and checks `doneWhen` again. If neither state matches, it stops for explicit
+inspection/repair. It does not guess that an existing object should be dropped.
+Retry the unchanged migration after repairing the actual database.
+
+A migration containing `CheckedSql` uses durable checkpoints for every step.
+Ordinary SQL within that migration commits its effect and completion checkpoint
+in the same transaction. Checked SQL records its phase before execution and checks
+actual state on restart. An interrupted success therefore need not execute twice.
+Attempted migration checksums are frozen even before the whole migration completes.
+
+This mode is not one atomic transaction: earlier successful steps remain committed
+when a later step fails. Contiguous ordinary migrations outside a mixed migration
+still form an atomic batch. The runner lock covers all these phases on the same
+connection; baseline and ordinary migration runners use the same lock protocol.
+Session lock behavior is documented by
+[PostgreSQL](https://www.postgresql.org/docs/current/explicit-locking.html#ADVISORY-LOCKS).
+
+Use `Migrator(db).progress()` or `dart run orm migrate status` to inspect step states, failed
+phases and failure codes. `dart run orm migrate plan` reports `atomic: false` for pending
+nontransactional work and includes progress. A `MIGRATION.STEP` exception retains
+the underlying error as `cause`. A failed lock release discards its connection.
+SQLite rejects `CheckedSql`; its schema rebuild path remains transactional.
+
+Tests terminate real Dart processes immediately after a concurrent DDL succeeds
+and after an ordinary step commits. Both resume from unchanged files without
+replaying committed work. They also exercise INVALID unique indexes, explicit
+repair, definition mismatches, lock timeout and simultaneous runners.
+
+# Existing databases
+
+```dart
+final result = await Migrator(db).baseline(
+ migrations,
+ expected: migrations.last.snapshot!,
+);
+```
+
+Baseline verifies declared columns, storage types, nullability, defaults, primary
+and unique keys, foreign keys, and simple indexes before recording history. It
+never replays creation SQL and refuses existing nonempty migration history.
+`verifySchema(...).matches` covers these supported facts; inspect `unmanaged`
+separately for triggers, policies, expression/partial indexes and unmodeled
+constraints/options. This catalog currently inspects the declared tables, not all
+objects in a database. PostgreSQL constraint removal resolves actual names by
+signature, including names chosen before an ORM baseline.
diff --git a/docs/mysql-migrations.md b/docs/mysql-migrations.md
new file mode 100644
index 00000000..8c559ca4
--- /dev/null
+++ b/docs/mysql-migrations.md
@@ -0,0 +1,134 @@
+# MySQL and MariaDB migrations
+
+Use one fixed `mysql` or `mariadb` migration history with its matching driver.
+The migration runner checks MySQL 8.4+ or MariaDB 11.8+ before taking a lock or
+creating its journal. The MySQL driver has the same 8.4 minimum; the MariaDB
+driver's 10.6 connection minimum does not extend migration support to that
+version. The normal Dart project workflow applies:
+
+```sh
+dart run orm init --database mysql
+dart run orm migrate create 0001_initial
+# Review migrations/m0001_initial.dart.
+dart run orm migrate check
+dart run orm migrate apply
+dart run orm migrate verify
+```
+
+`init --database mariadb` selects MariaDB instead. Models, physical snapshots,
+reviewed migration operations and the static registry are all Dart source. A saved
+migration contains SQL for its selected engine only; current application models
+are not imported by historical migration files. See [migrations](migrations.md)
+for configuration, fingerprints, deployment bundles, baseline and version checks.
+
+## DDL and recovery
+
+MySQL and MariaDB DDL commits independently of application transactions. MySQL's
+atomic DDL guarantees do not make a sequence of DDL statements transactional.
+The runner consequently executes each reviewed `CheckedTableSql` outside a
+transaction, holding one session lock for the selected database. The step records
+its SQL and complete physical table definitions before and after the operation.
+A null `before` means creation; a null `after` means removal. Different table names
+mean an explicit rename. [MySQL atomic DDL](https://dev.mysql.com/doc/refman/8.4/en/atomic-ddl.html)
+
+For each unfinished step, the runner:
+
+1. Records an attempted step with the immutable migration fingerprint.
+2. Compares the live catalog with the complete `after` definition. An exact match
+ means the DDL is already complete, including when its response was lost.
+3. Otherwise requires an exact `before` definition, executes the SQL, and verifies
+ the complete `after` definition before recording completion.
+4. Stops if neither definition matches. Repair the database, then retry the same
+ unchanged history. An object with the right name and wrong shape is rejected.
+
+Checks cover column storage, nullability, identity/default/computed expressions,
+primary and unique keys, indexes, foreign keys and checks. Unmodeled table options,
+triggers, unsigned columns, unsupported indexes and other catalog objects block
+checked DDL and backfill. The runner does not silently discard them. Expression comparison understands
+common arithmetic, comparison, boolean and function forms and preserves operator
+precedence. Other SQL syntax uses strict token comparison; a different server
+rendering is reported as drift instead of being assumed equivalent.
+
+Completed checkpoints form a durable prefix. A later failure does not roll back
+earlier DDL. `migrate status` exposes the step, phase and failure; retrying `apply`
+continues the same history. Applied or attempted migrations with changed
+fingerprints are rejected. The final declared snapshot is verified before the
+migration itself is recorded as applied.
+
+The runner uses `GET_LOCK`/`RELEASE_LOCK` with a database-specific key and
+`Migrator(..., lockTimeout: ...)`. Lock ownership stays with one physical session.
+A failed acquisition or uncertain release discards that connection. These locks
+coordinate ORM migration runners; they do not block independent administrative
+DDL or normal application writes. Use deployment coordination for those changes.
+[MySQL named locks](https://dev.mysql.com/doc/refman/8.4/en/locking-functions.html)
+
+## Data changes
+
+`ExecuteSql` accepts `INSERT`, `UPDATE`, `DELETE` and `REPLACE` for these engines.
+Each such step and its completion checkpoint share an InnoDB transaction. Raw
+DDL, transaction control and session administration are rejected during validation;
+use a reviewed `CheckedTableSql` for DDL. Keep manual DML within managed InnoDB
+tables: arbitrary SQL targeting external nontransactional tables cannot inherit
+InnoDB rollback guarantees.
+
+`Backfill` keeps its historical table definition and immutable primary-key cursor.
+It locks a bounded batch with `SELECT ... FOR UPDATE`, updates exactly those keys,
+and commits the row changes and cursor together. This does not require MySQL
+`UPDATE ... RETURNING`. Triggers or other unmanaged table behavior are rejected,
+and retained primary keys are checked before advancing. `maxBackfillBatches`
+bounds one invocation; a later `apply` resumes its saved cursor.
+
+Add a nullable column, backfill it, then make it required in a later migration.
+The diff generator will not add a populated required column without a default or
+backfill stage. Primary keys must stay immutable while the backfill runs.
+Application writes must preserve the completion condition during deployment.
+
+## Supported schema changes
+
+Creation, explicit table/column renames, column addition/removal, defaults,
+nullability, signed integer/decimal/temporal widening, primary and unique keys,
+ordinary indexes, foreign keys and named checks produce reviewed table steps.
+Foreign keys are created after their tables, including cyclic relationships.
+Their required supporting indexes have deterministic names and appear in the
+frozen schema, so InnoDB does not create invisible schema drift on the ORM's behalf.
+Destructive drops require `allowDestructive`; renames are never inferred.
+
+Automatic narrowing, codec changes, identity changes, generated-to-ordinary
+changes and changes between virtual/stored generated columns are rejected during
+planning. Use explicit replacement columns and backfill, or author a reviewed
+`CheckedTableSql` with accurate historical definitions. MySQL has no PostgreSQL
+`ALTER ... USING`; the `using` diff option is rejected. Give checks explicit names
+if they may need to be removed or changed later.
+
+Physical defaults are signed `BIGINT`, `VARCHAR(255)` with `utf8mb4_bin`, `DOUBLE`,
+`TINYINT(1)`, `LONGBLOB`, `DATE`, `TIME(6)` and `DATETIME(6)`. Decimal columns require
+explicit precision 1–65 and scale 0–30 not exceeding precision. Tables use InnoDB
+and `utf8mb4_bin`. MariaDB JSON is its native JSON alias, including the generated
+validity check; catalog inspection recognizes that representation. `TINYINT(1)`
+does not itself restrict values to zero and one. DATETIME catalog metadata does
+not identify whether an application intends a UTC instant or a local date/time.
+
+A declared temporal precision below six delegates storage coercion to the engine;
+rounding/truncation can differ by engine and SQL mode. The ORM does not promise
+cross-engine rounding for these columns. The default six digits preserve Dart's
+microsecond precision. Computed expressions and checks can specify separate
+`mysql:` and `mariadb:` SQL; each history freezes only its selected expression.
+
+Catalog verification reports unsupported features rather than guessing a mapping:
+unsigned/zerofill and binary-string types, prefix/expression/descending/invisible
+indexes, nondefault table options, cross-database foreign keys and custom foreign
+constraint names. An imported database can be verified and baselined while
+reporting unmanaged objects; automated checked changes require resolving them
+first. [MySQL column metadata](https://dev.mysql.com/doc/refman/8.4/en/information-schema-columns-table.html),
+[MariaDB column metadata](https://mariadb.com/docs/server/reference/system-tables/information-schema/information-schema-tables/information-schema-columns-table)
+
+## Verification
+
+`test/mysql_migration_test.dart` uses `ORM_TEST_MYSQL` and `ORM_TEST_MARIADB` and
+optional matching `_TLS` variables. It creates an isolated disposable database
+per test and therefore needs `CREATE DATABASE` privileges. Tests cover catalog
+round trips, lost DDL acknowledgements, drift rejection, transactional checkpoint
+failures, unknown commit outcomes, lock release, bounded backfill, explicit
+renames, relationships and baseline. A compiled consumer imports generated Dart
+migrations and checks their fingerprints for both engines. An unset
+engine environment variable skips its live tests; static planning tests still run.
diff --git a/docs/mysql.md b/docs/mysql.md
new file mode 100644
index 00000000..41c92eed
--- /dev/null
+++ b/docs/mysql.md
@@ -0,0 +1,209 @@
+# MySQL and MariaDB
+
+The native drivers use `mysql_client_plus` and require MySQL 8.4+ or MariaDB
+10.6+. SQLite, PostgreSQL, MySQL and MariaDB remain distinct database engines.
+Opening a MySQL driver against MariaDB, or the reverse, fails before use.
+
+## Use the driver alone
+
+```dart
+import 'package:orm/drivers/mysql.dart';
+
+final driver = await MysqlDriver.open(
+ MysqlOptions(url: Uri.parse('mysql://user:password@localhost/app')),
+);
+try {
+ final result = await driver.run(
+ (connection) => connection.execute(
+ SqlCommand('SELECT name FROM users WHERE id = ?', [42]),
+ ),
+ );
+ print(result.rows);
+} finally {
+ await driver.close();
+}
+```
+
+For MariaDB, import `package:orm/drivers/mariadb.dart` and use
+`MariadbDriver.open(MariadbOptions(...))`. Its URL may use `mariadb://` or
+`mysql://`; the server identity must still be MariaDB. These libraries do not
+import ORM models, query builders, generation, or migration tooling.
+
+All parameterized statements use the server's binary prepared-statement
+protocol. Statements without parameters use the text protocol; the upstream
+client's prepare operation cannot complete zero-parameter, zero-column
+statements such as DDL and `ROLLBACK`. The driver never uses the client's named
+parameter interpolation. Result columns preserve their order and duplicate
+names; generated identities come from the server response as `lastInsertId`.
+
+## Typed queries and mutations
+
+Import `package:orm/mysql.dart` and open `mysql(MysqlOptions(...))` for a
+`Database`, or use `package:orm/mariadb.dart` and
+`mariadb(MariadbOptions(...))`. The independent `SqlBuilder` can also compile
+the same queries without opening a connection. Bind values separately; the
+compiler orders positional parameters by their final SQL occurrence.
+
+Neither adapter advertises `RETURNING`. `createRow` instead inserts and reads
+the result by primary key on the same transaction connection. It starts a
+transaction when necessary and reuses an existing transaction. Primary keys
+must be supplied as literal assignments, with at most one omitted generated
+identity; tables without a primary key and keys computed by arbitrary SQL are
+rejected before insertion. Precision-coerced primary-key assignments are also
+currently rejected because the stored key can differ from the input. A failed
+read or decode marks the transaction failed, even if application code catches
+the exception. Plain `insert(...).execute()` remains available when no returned
+row is needed.
+
+Use `onDuplicateKeyUpdate` explicitly for native MySQL/MariaDB upserts. Any
+duplicate primary or unique key can cause the update; callers cannot select a
+particular conflict target. `onConflictUpdate` and `onConflictDoNothing` are
+rejected. A self-assignment would still run update triggers, so it is not a
+substitute for doing nothing. Affected-row counts follow the server's insert
+and update semantics.
+
+Typed JSON parameters are parsed as JSON expressions, and final projections
+convert JSON to character text only when crossing the driver decoding
+boundary. CTEs, scalar subqueries, and UNION operands retain native SQL values.
+Use `Codecs.jsonDocument.nullable()` to distinguish `SqlJson(null)` from SQL
+`null`. Direct `.distinct()` with a JSON result is rejected: deduplicate native
+values inside a CTE, then read that CTE so the character conversion happens
+afterwards:
+
+```dart
+final unique = db.table(documents)
+ .select((row) => row.document)
+ .distinct()
+ .asCte('unique_documents');
+final values = await unique.query.get();
+```
+
+JSON equality follows the selected engine. MySQL has native JSON storage;
+MariaDB stores JSON as validated text. The ORM does not promise identical
+object ordering, duplicate-key, or comparison behavior across engines.
+
+Exact decimals use at most 65 digits and scale 0–30, with scale no larger
+than precision. Big integers use `DECIMAL(65,0)`. Typed parameters are cast to
+decimal storage so comparisons do not fall back to floating point. Column
+constraints and MIN/MAX are available within engine limits. Explicit decimal `rounded`, `divide`,
+`divideExpression`, and `average` reject unsupported exact-rounding semantics
+instead of substituting approximate arithmetic. Decimal addition, subtraction and
+multiplication and SUM reject `CAPABILITY.DECIMAL_PRECISION`: native arithmetic can
+silently truncate fractional digits even when neither input exceeds the storage
+limit, and a native SUM can saturate when materialized by a subquery. The
+`exactDecimal` capability describes lossless values and comparisons, not all
+arithmetic operators. Explicit expression `constrained` and decimal UNION/UNION ALL
+are also rejected because the engines may silently clamp or narrow precision.
+Assignments rely on the declared column and strict SQL mode rather than first
+casting into a narrower intermediate value. Explicit `sql(...)` expressions remain available for applications that
+accept the selected engine's bounded arithmetic semantics.
+
+Temporal column precision is enforced by the selected engine on assignment;
+rounding or truncation follows that engine and its session modes. Explicit
+expression `withPrecision` is rejected because its cross-engine rounding
+contract is not implemented for these engines.
+
+## Connection ownership and limits
+
+Each driver owns one physical connection. It queues complete `run` callbacks,
+so transactions cannot interleave with another lease. Statements inside one
+callback must be awaited before the next statement starts. A connection
+cannot be used after its callback completes. `close()` waits for already
+accepted work, and every concurrent close caller waits for the same result.
+
+Lease release runs `ROLLBACK`, including after a successful callback, because
+raw callers may leave a transaction open. Commit explicitly to persist a
+transaction. This cleanup is one additional database round trip per lease;
+several statements can share a lease. Session variables and temporary tables
+belong to the connection and are not recreated for each lease.
+Raw callers that change `autocommit`, `sql_mode` or `time_zone` must restore
+the driver's documented settings before leaving that lease. In particular,
+leaving autocommit disabled makes later writes part of an uncommitted transaction
+that lease cleanup rolls back. Use managed transactions for application writes.
+
+Results are materialized. `streaming` and `cancellation` capabilities are
+false; requesting either reports an unsupported capability. `statementTimeout`
+is true: `ExecutionOptions(timeout: ...)` bounds an individual statement through
+the raw runtime and ORM, overriding the driver's `queryTimeout` default.
+Query timeouts discard the connection. A timeout or connection loss does not
+prove a write failed or rolled back, so an uncertain write must not be retried
+automatically. Open a new driver after invalidation or disconnection; there is
+no implicit reconnect. Transaction deadlines, cancellation tokens and retry
+policies still require actual cancellation and remain unsupported.
+
+The underlying client does not expose the server transaction status flags,
+so `transactionActive` is `null`. The driver does not guess state from SQL
+text. `SqlDatabase` and ORM transactions therefore check every statement,
+including SQL executed on a connection borrowed through `tx.run`. Only one
+SELECT, INSERT, UPDATE, DELETE, REPLACE, WITH, SHOW, DESCRIBE or EXPLAIN statement
+is accepted. DDL, manual transaction control, SET, CALL, dynamic execution,
+executable comments, multiple statements and ambiguous quoted backslash
+escapes fail with `TRANSACTION.STATEMENT` before reaching the server. Use
+`transaction()` and `savepoint()` for transaction boundaries, and bind values
+separately. A caught statement failure still prevents committing that scope;
+a savepoint can isolate a recoverable failure.
+
+MySQL/MariaDB DDL may implicitly commit and cannot be made atomic by a Dart
+callback. Run DDL outside runtime transactions, using the engine-specific
+migration workflow. The independent low-level driver executes raw SQL without
+this runtime guard and leaves transaction control to its caller.
+
+## TLS and session behavior
+
+`MysqlTls.verifyFull` is the default. It rejects invalid certificates rather
+than inheriting the upstream client's permissive default. Supply a Dart
+`SecurityContext` for private trusted certificate authorities.
+`MysqlTls.require` deliberately skips certificate verification and is for
+explicitly trusted environments such as local integration fixtures.
+`MysqlTls.disable` is unencrypted; the current client requires TLS for
+SHA-2 authentication, including MySQL's usual `caching_sha2_password` path.
+
+Initialization sets the session time zone to UTC. It retains existing SQL
+modes and adds `ANSI_QUOTES`, `NO_BACKSLASH_ESCAPES`, `STRICT_ALL_TABLES`,
+`NO_ZERO_DATE`, `NO_ZERO_IN_DATE`, `ERROR_FOR_DIVISION_BY_ZERO`, and
+`NO_ENGINE_SUBSTITUTION`. Double quotes therefore quote identifiers, and a
+backslash in a string literal is an ordinary character. Bind values with
+parameters instead of depending on string-literal escaping.
+
+## Value boundaries
+
+- Signed integer columns decode exactly into Dart's signed 64-bit `int`.
+ Decimal columns stay decimal text and pass through `Codecs.decimal` without
+ rounding through `double`. `BigInt` and `Decimal` inputs bind exact text.
+- Boolean columns return integer `0` or `1`, which `Codecs.boolean` decodes.
+- `BLOB` columns return bytes. The upstream binary decoder does not safely
+ support all `BINARY`/`VARBINARY` columns or unsigned integer columns; those
+ are outside this adapter's supported storage contract. For raw access,
+ explicitly cast unsigned integers to character text and use `HEX(...)`
+ for unsupported binary storage rather than relying on its decoder.
+- Native `DateTime` parameters are converted to UTC; local date/time types
+ retain their calendar meaning. Dates are limited to years 1000–9999.
+ Binary temporal results preserve microseconds, including `.000001`.
+ MySQL `TIME` can represent signed durations beyond 24 hours; such values
+ are not `LocalTime` and should remain raw strings.
+- Select JSON as `CAST(document AS CHAR CHARACTER SET utf8mb4)` for a
+ lossless JSON text boundary. This distinguishes SQL `NULL` from JSON
+ `null`, and works on both engines. The upstream decoder otherwise erases
+ this distinction for a direct MySQL JSON column. Its parsed non-null JSON
+ results are wrapped in `SqlJson` so JSON string scalars remain strings.
+
+## Real database tests
+
+`test/mysql_driver_test.dart` imports only the low-level driver libraries.
+Set `ORM_TEST_MYSQL` and `ORM_TEST_MARIADB` to disposable database URLs.
+The corresponding `ORM_TEST_MYSQL_TLS` and `ORM_TEST_MARIADB_TLS` variables
+choose `verifyFull`, `require`, or `disable` (default `verifyFull`).
+
+```sh
+dart test test/mysql_driver_test.dart
+```
+
+The suite covers actual prepared statements, values, commit/rollback,
+savepoints, abandoned transaction cleanup, error recovery, engine mismatch,
+lease serialization, close draining, invalidation, and timeout handling.
+Without a database URL that engine's integration group is explicitly skipped.
+See `docs/progress.md` for which server versions have actually been validated.
+`test/mysql_database_test.dart` exercises typed queries, JSON and decimal
+boundaries, generated-row reads, relations, and transaction behavior.
+`test/sql_mysql_review_test.dart` adds compiler and fault-injection regressions;
+these synthetic checks do not replace the real database suites.
diff --git a/docs/named-sql.md b/docs/named-sql.md
new file mode 100644
index 00000000..becee610
--- /dev/null
+++ b/docs/named-sql.md
@@ -0,0 +1,171 @@
+# Named SQL queries
+
+Declare parameters and results as Dart records, keep complex SQL in files, and
+generate a typed database method. This path uses the same Query, Selection,
+connection, transaction and cursor implementation as generated tables.
+
+```dart
+import 'package:orm/schema.dart';
+
+typedef AuthorStats = ({String author, int postCount, int points});
+final authorStats = sqlQuery(
+ sqlite: 'stats.sqlite.sql',
+ postgres: 'stats.postgres.sql',
+);
+```
+
+The SQLite file:
+
+```sql
+SELECT author, COUNT(*) AS post_count, SUM(points) AS points
+FROM posts
+WHERE points >= :minimum AND (:author IS NULL OR author = :author)
+GROUP BY author;
+```
+
+Use `SUM(points)::bigint AS points` in the PostgreSQL file when the result is
+intended to fit Dart's signed integer range. The files may differ or both dialects
+may reference the same file. Paths are relative to the declaring Dart library.
+
+```sh
+dart run orm queries generate lib/queries.dart
+dart run orm queries check --source lib/queries.dart --sqlite app.db
+dart run orm queries check --source lib/queries.dart \
+ --postgres-env DATABASE_URL --database-schema public
+```
+
+Generation writes only `queries.queries.dart`. It works
+offline, analyzes source types and codecs, and verifies that every dialect's
+parameter names match the declared record. Commit this output with the SQL and
+source declaration. `queries check` first re-analyzes the source and compares the
+generated Dart code; stale SQL, declarations or edited generated code require regeneration.
+
+For a custom generated location, add `--output path.dart` to `queries check`.
+The programmatic equivalent is `checkGeneratedQueries(source, output: path)`.
+
+Import the generated file to use the method:
+
+```dart
+final stats = await db.authorStats(minimum: 2, author: 'a').single();
+final names = await db.authorStats(minimum: 0)
+ .where((s) => s.points.gt(10))
+ .orderBy((s) => [s.author.asc()])
+ .select((s) => s.author)
+ .get(); // List
+
+await db.transaction((tx) async {
+ final rows = await tx.authorStats(minimum: 0).get();
+ // This query uses the transaction's connection and sees its pending writes.
+});
+```
+
+Non-null parameter fields generate required named arguments. Nullable parameters
+default to SQL NULL. Use `()` for no parameters. The result must be a public,
+non-generic named-record typedef in the declaring file. Parameters may use such a
+typedef or an inline named record. Enums and `@UseCodec` use the ordinary generator's
+type and codec analysis. Result names use snake_case by default; `@ColumnName`
+selects an explicit SQL alias. Query declarations do not accept identity, default,
+index, integer-width or decimal-precision column metadata.
+
+A declaration containing only `postgres:` generates an extension on
+`Database`, so SQLite code cannot call it. A declaration containing both
+targets works on either backend. Database checks validate only the selected target;
+run both commands when shipping both files.
+
+## What the checks establish
+
+SQLite compiles `EXPLAIN SELECT FROM ()`. PostgreSQL
+uses SQL `PREPARE` for that projection, reads the prepared statement's native
+result types, then deallocates it on the same leased connection. Neither path
+executes the application SELECT. Missing tables, missing declared aliases and
+invalid SQL fail. PostgreSQL also checks storage-type families against the declared
+codecs. Its checker is verified against PostgreSQL 18.4, including the
+`pg_prepared_statements.result_types` catalog column. These paths follow the
+[PostgreSQL PREPARE lifecycle](https://www.postgresql.org/docs/current/sql-prepare.html),
+[prepared-statement metadata](https://www.postgresql.org/docs/current/view-pg-prepared-statements.html),
+and [SQLite EXPLAIN behavior](https://www.sqlite.org/lang_explain.html). The checker
+does not parse SQLite's version-dependent EXPLAIN output.
+
+MySQL and MariaDB use SQL `PREPARE` and `DEALLOCATE PREPARE` on one session,
+without `EXECUTE`. The checker binds its SQL text through a temporary session
+variable and clears it afterwards. It validates syntax, table references and
+declared result aliases, but reports storage types and nullability as unchecked.
+This follows the [MySQL PREPARE lifecycle](https://dev.mysql.com/doc/refman/8.4/en/prepare.html)
+and [MariaDB PREPARE lifecycle](https://mariadb.com/docs/server/reference/sql-statements/prepared-statements/prepare-statement).
+Ordinary `EXPLAIN` is unsuitable for this guarantee: our MariaDB 11.8 fixture
+executes a stored function with an INSERT side effect during planning.
+
+These checks do not infer expression nullability, integer range, decimal scale,
+enum labels or custom codec correctness. Integer declarations can accept native
+NUMERIC metadata, but a fractional or out-of-range value still fails integer
+decoding. SQLite expression values may change storage class between rows; their
+types are checked by the result codecs at runtime. Declare nullable fields for
+nullable SQL expressions. The report explicitly records `nullabilityChecked: false`.
+Only emitted projections are checked; source columns not selected by the record
+may remain in the SQL.
+
+Generation itself performs lexical parameter scanning, not full SQL parsing.
+Native structure checks belong in development/CI against the intended schema.
+They prove acceptance at check time; they do not certify a future migrated schema
+or persist an approval flag in runtime code.
+
+## Composition and execution
+
+The generated result is an ordinary immutable Query with a fixed SQL CTE source.
+Typed filtering, projections, CTEs, subqueries, grouping/windows and streaming
+remain available. The SQL source has no inferred key or cardinality: use `take(1)`
+for a scalar subquery and supply normal outer ordering/limits. Keyset pagination
+cannot invent a unique key for a SQL result. Generated table mutations are rejected
+for this CTE source. This declaration path supports SELECT/WITH/VALUES queries;
+use the existing mutation APIs or parameterized `Database.execute` for writes.
+
+As with table queries, select SQL expressions before UNION, then map the result:
+
+```dart
+final a = db.authorStats(minimum: 0, author: 'a').select((s) => s.author);
+final b = db.authorStats(minimum: 0, author: 'b').select((s) => s.author);
+final authors = await a.unionAll(b).get();
+```
+
+Native SQL can call functions with side effects. The query wrapper does not prove
+purity. Such SQL retains the database's ordinary execution and transaction rules.
+SQL paths and text are application code; user input belongs in bound parameters.
+`:name` is the sole placeholder syntax. Repeated names bind once. Quoted strings,
+identifiers, comments, PostgreSQL casts and dollar-quoted text are preserved.
+PostgreSQL backslashes in strings require explicit `E'...'` or dollar quoting.
+Only one statement is accepted, with an optional terminal semicolon. Internal CTE
+names use `_orm_sql_`; avoid that namespace in application SQL.
+
+Physical dependencies are opaque to the ORM. `watch()` therefore requires explicit
+tables, including dependencies hidden in views/functions:
+
+```dart
+db.authorStats(minimum: 0).watch(reads: [postsSchema]);
+```
+
+The subscription follows the same committed-invalidation rules as other queries.
+SQL source ordering alone does not establish the ordering of an outer query.
+
+## Incremental generation
+
+```yaml
+targets:
+ $default:
+ builders:
+ orm:queries:
+ enabled: true
+ generate_for:
+ - lib/queries.dart
+```
+
+Run `dart run build_runner watch`. Both the Dart library and referenced SQL assets
+participate in dependency tracking. Imported enum/codec declarations are tracked
+by the analyzer resolver. A SQL parameter mismatch fails the build; fixing the
+file restores output. This builder is independent of `orm:orm`, and a library may
+contain both entity and named-query declarations when both builders target it.
+
+The native fixtures cover both dialects, transactions, cursor reads, typed temporal
+and Decimal parameters, raw-SQL subscriptions, failed structure checks and absence
+of expression evaluation during checking. A compiled macOS executable exercises
+the generated SQLite runtime without the analyzer. Browser, Flutter and query
+throughput acceptance are separate work.
diff --git a/docs/observability.md b/docs/observability.md
new file mode 100644
index 00000000..6f803c6c
--- /dev/null
+++ b/docs/observability.md
@@ -0,0 +1,118 @@
+# Query plans and execution observations
+
+`query.inspect()` describes the SQL the ORM will request without acquiring a
+connection, executing statements or invoking result mappers. It works with the
+same query builder used by `get()` and `stream()`:
+
+```dart
+final query = db.users.select((u) => (
+ u.name,
+ u.memberships
+ .orderBy((m) => [m.joinedAt.desc(), m.teamId.desc()])
+ .take(2)
+ .select((m) => m.team.select((t) => t.name).required())
+ .many(),
+).map((name, teams) => (name: name, teams: teams)));
+
+final plan = query.inspect();
+print(plan.sql);
+print(plan.loads.single.query!.sql);
+print(plan.toJson());
+final rows = await query.get();
+```
+
+Run `dart run example/teams/main.dart` for a complete generated-schema example.
+Inspection compiles SQL on demand; normal execution does not construct this
+description. Query compilation and structural errors can surface during inspection.
+
+## What the description contains
+
+Each `QueryPlan` contains one statement and its dependent `RelationLoadPlan`s.
+Its immutable lists describe:
+
+- SQL and parameter count, excluding bound parameter values. Literal text in raw
+ or named SQL is retained, so this is not a general SQL redaction mechanism.
+- Physical output slots, including association keys and joined presence markers.
+ `codecType` names the logical codec SQL type, not necessarily the database's
+ physical storage type. Expressions without direct column origins omit table
+ and column names. Slot indices start at zero.
+- Explicit and generated relationship joins, with table/CTE source names and
+ left/inner join kind. Joins inside subqueries remain visible in the SQL text.
+- Known table reads for this statement, including CTEs and subqueries. Child
+ batch reads belong to their own plans. Raw SQL and named SQL set `opaqueReads`
+ because the compiler does not parse their dependencies.
+- Each batch's parent/child key slots, composite key width, per-parent limit and
+ offset, fixed parameter count, and maximum parent keys per chunk.
+
+A child SQL template contains placeholders for **one** parent key tuple. Its
+parameter count therefore equals `fixedParameters + keyWidth`. Runtime expands
+the key placeholders to match each actual chunk. The capacity is:
+
+```text
+maxKeysPerBatch = (driver.maxParameters - fixedParameters) ~/ keyWidth
+```
+
+`sqlTemplateCount` counts statement templates in the tree. It is not an execution
+count: empty parent results skip child statements, repeated keys share a lookup,
+and large key sets require multiple chunks. Composite keys containing NULL do
+not join through equality. For one active relationship at one level, child
+statement count is `ceil(distinct non-null parent keys / maxKeysPerBatch)`.
+Nested loads apply that rule separately to each returned parent batch, and
+streaming applies it for each root fetch batch. `take(0)` has a skipped load with
+no child SQL. Selected to-one JOINs are already part of their parent's statement.
+
+This description does not estimate database page reads, optimizer choices, row
+volume or elapsed time. Native optimizer inspection is a separate operation:
+[PostgreSQL EXPLAIN](https://www.postgresql.org/docs/18/sql-explain.html) and
+[SQLite EXPLAIN QUERY PLAN](https://www.sqlite.org/eqp.html) consult the database.
+PostgreSQL's `ANALYZE` option actually executes the statement. The ORM does not
+issue either command automatically.
+
+## Measuring execution phases
+
+```dart
+final db = await sqlite(
+ const SqliteOptions.memory(),
+ onAcquire: (event) => print((event.elapsed, event.reusedConnection, event.error)),
+ onQuery: (event) => print((event.operation, event.rowCount, event.elapsed)),
+ onDecode: (event) => print((event.inputRows, event.elapsed, event.error)),
+);
+```
+
+`Database`, `postgres` and `sqlite` accept the same optional hooks.
+Sessions, transaction attempts and savepoints inherit them.
+
+| Hook | Measured interval | Limits |
+| --- | --- | --- |
+| `onAcquire` | Driver lease request until callback entry or acquisition failure | Includes pool wait and setup inside that request. Does not separate those driver internals. Initial SQLite/worker opening occurs before the Database exists and is excluded. |
+| `onQuery` | Driver statement or cursor operation until completion/failure | Includes driver conversion and transport, not only server CPU. SQL and parameter count are recorded, bound values are excluded. Cursor fetches report their actual returned row counts. |
+| `onDecode` | Synchronous ORM codec/mapping and related-row grouping | Excludes SQL, acquisition, compilation, consumer pauses and other client work. `inputRows` counts rows presented to that decode batch, including on failure. |
+
+An operation within an existing session/transaction reports
+`reusedConnection: true` and zero acquisition time. A root query and its collection
+loads use one acquisition. Acquisition timeout/cancellation reports a failed
+event; returning a later lease does not report a second success or start SQL.
+Invalid options and already-cancelled requests fail before acquisition begins.
+
+Each root result, child chunk and nonempty stream fetch has a decode event.
+Nested child results are decoded before their parent result. Returning mutations
+use their command SQL; batch RETURNING combines command results and reports
+`sql: null`. Raw `Database.execute` returns driver rows without ORM decoding.
+Empty `get()` results can report zero input rows; an exhausted stream's empty
+fetch needs no decode event.
+
+Callbacks are synchronous. Their exceptions are ignored, preserving the actual
+operation result and original error. Measurement stops before invoking each
+callback, but callback work still delays the caller; keep it small. With hooks
+omitted the ORM creates no observation events or measurement Stopwatches.
+
+These intervals are not a complete decomposition of total latency: compilation,
+some relation bookkeeping, scheduling and caller work are outside them. Concurrent
+operations may interleave events; callbacks do not provide trace correlation IDs.
+Neither a successful SQL event nor a decode error alone establishes a transaction's
+commit outcome. A result mapper runs in the existing mutation lifecycle and can
+fail after an autocommitted write; observation does not move transaction boundaries.
+
+Real backend and browser coverage checks event scopes, query/row counts,
+acquisition waiting/cancellation and observer failures. Runtime throughput and
+allocation comparisons remain a separate [acceptance gate](acceptance.md).
diff --git a/docs/performance.md b/docs/performance.md
new file mode 100644
index 00000000..289572a9
--- /dev/null
+++ b/docs/performance.md
@@ -0,0 +1,246 @@
+# Runtime cost measurements
+
+Run the same native SQL and result shapes through the public driver and ORM:
+
+```sh
+ORM_TEST_POSTGRES='postgresql://localhost/orm_bench' dart run tool/benchmark_runtime.dart
+```
+
+The PostgreSQL account needs permission to create/drop its own temporary schema.
+The tool removes that schema and its temporary SQLite WAL file when finished.
+It does not alter the application's tables. `--smoke` uses five timing samples
+and writes `.dart_tool/runtime-smoke.json`; it validates the harness and is not
+a performance result. The normal run records
+[`research/benchmarks/runtime.json`](../research/benchmarks/runtime.json).
+Use `--output ` to retain a subsequent measurement separately from that
+baseline, for example `--output research/benchmarks/runtime-selection.json`.
+
+## Comparison contract
+
+Both paths use the **same public Driver**: PostgreSQL pooling/protocol/decoding,
+or the native SQLite background isolate and its message transport. The raw path
+calls `driver.run` and `connection.execute` directly, then constructs the same
+Records/lists using the same public codecs. This isolates the query layer above
+the adapter. It is not a comparison against synchronous `package:sqlite3` on the
+main isolate or an independently configured `package:postgres` connection.
+
+The raw path reuses captured, precompiled SQL. Its relationship loader derives
+keys from the returned parent rows, fills the same parameter positions, groups
+children and returns unmodifiable child lists. The fixture has a fixed root/key
+count; this baseline is handwritten for that workload, not a general replacement
+for the ORM query planner. Raw SQL, parameter values, statement count and complete
+business results are checked against the corresponding generated ORM query.
+Independent assertions check root count, per-parent ordering/limits and grouped
+counts. All data belongs to the generated [example schema](../example/schema.dart).
+
+| Case | Result | Expected SQL result volume |
+| --- | --- | --- |
+| `full_rows` | 100 complete User Records; nullable, long Unicode nicknames | 100 rows, one statement |
+| `two_columns` | 100 `(id, email)` Records | 100 rows, one statement |
+| `three_posts` | 100 users with their latest three `(id, title)` posts | 100 parent + 300 child rows, two statements |
+| `aggregate` | Counts for ten score groups | 10 rows, one statement |
+
+The database contains 100 users and 1,000 posts. Field selection reduces returned
+columns; per-parent pagination returns 300 of those posts. This sample does not
+measure arbitrary graph cardinalities, mutation throughput or every codec.
+
+## Timing and transport
+
+Each backend runs in a separate native JIT process. Query objects, schema,
+connections and database caches are warm. Query object construction is outside
+the timing; ORM SQL compilation on each `get()` is inside it. The default hooks,
+VM service and profiler are disabled in the timing processes.
+
+For each case, 20 raw/ORM pairs warm the code before 200 measured pairs. The first
+lane alternates in each measured pair. Both lanes retain their actual duration
+samples, with nearest-rank p50/p95. In the paired timing section, `wallMicros`
+sums measured operation intervals and operations/second is the inverse mean
+duration. It excludes the gaps between those intervals. The separate closed-loop
+concurrency section runs 200 operations per lane across eight clients, and its
+wall time/throughput covers the entire concurrent run. It runs raw then ORM;
+repeat measurements to assess order/load/JIT variability.
+
+SQLite uses one worker connection and a temporary WAL file. PostgreSQL warms all
+four pool slots. These backend configurations serve different purposes; their
+absolute throughputs are not a driver ranking.
+
+Both PostgreSQL timing scenarios use an external loopback TCP relay. One forwards
+immediately. The other schedules each received chunk after 10 milliseconds in
+each direction, preserving order without serially adding a delay for every chunk.
+An independent byte echo measures the relay's actual round-trip latency and checks
+its byte accounting. The report also measures `SELECT 1` through the complete
+driver. That command can involve multiple protocol round trips: a SQL statement
+count is not a TCP round-trip count.
+
+This is controlled transport latency on a local database, not a remote database
+deployment. It does not simulate WAN loss, bandwidth limits, TLS or a remote
+server's CPU/storage. The relay and its counters run in the controller process,
+outside the benchmark process's measured heap.
+
+## Observation and memory scopes
+
+Separate probes preserve SQL/parameters, returned-row counts and UTF-8 JSON byte
+lengths of the driver rows and normalized result. These JSON lengths describe
+logical payload volume, not native heap sizes or SQLite IPC encoding. PostgreSQL
+also records bytes received/sent by its relay during each probe, including
+protocol messages but excluding TCP/IP headers. Connection setup is already done.
+
+A separate instrumented eight-client run records 64 acquisition samples per lane
+and statement durations. These are driver lease times, including setup inside the
+request; they do not isolate the pool implementation's queue time. The ORM probe
+also records synchronous decode/grouping times. These probes do not contribute to
+the default latency samples.
+
+Memory profiling uses fresh local processes after timing. The external controller
+queries the SDK VM service, requests GC, runs three reads retaining the last result,
+then inspects live heap state. Reports include heap/external memory, selected live
+class counts, RSS before/after and process-lifetime maximum RSS. The latter can
+include startup and previous cases; it is not a per-query peak. Live heap statistics
+cover the isolate group, including SQLite's worker, and are not solely result size.
+
+The SDK's protocol describes allocation accumulators, but
+[Dart 3.13.3's implementation](https://github.com/dart-lang/sdk/blob/3.13.3/runtime/vm/class_table.cc#L263)
+emits current counts/sizes for both the accumulated and current fields. This
+benchmark therefore does not subtract `accumulatedSize` values or describe a live
+heap delta as total allocated bytes. The
+[service implementation](https://github.com/dart-lang/sdk/blob/3.13.3/runtime/vm/service.cc#L4443)
+also establishes the isolate-group scope of its GC/profile operation.
+
+Instead, a separate
+[allocation trace](https://github.com/dart-lang/sdk/blob/3.13.3/runtime/vm/service/service.md#getallocationtraces)
+counts observed creations of selected Record, List, Map and selection-plan classes
+in the main query isolate, and records allocation frames. It excludes untraced
+classes, native allocations and the SQLite worker's allocation traces. Buffer and
+stack limits apply; truncated stack counts are retained. These are observed traces,
+not an exact census of every allocation or a measurement of total allocated bytes.
+Tracing can deoptimize code and changes execution cost; no traced durations are
+used as normal throughput results.
+
+## Interpretation
+
+Captured on 2026-09-15 with an Apple M3 Max, Dart 3.13.3, SQLite 3.53.4 and
+PostgreSQL 18.4. Runtime source is `94d24fe`. Durations below are milliseconds;
+throughput is operations/second for the separate eight-client run.
+
+| Environment | Case | Raw p50 | ORM p50 | ORM p95 | ORM concurrent ops/s |
+| --- | --- | ---: | ---: | ---: | ---: |
+| SQLite WAL | full rows | 0.111 | 0.160 | 0.242 | 6,919 |
+| SQLite WAL | two columns | 0.055 | 0.075 | 0.127 | 14,159 |
+| SQLite WAL | three posts | 0.728 | 0.817 | 0.915 | 1,238 |
+| SQLite WAL | aggregate | 0.036 | 0.040 | 0.049 | 24,564 |
+| PostgreSQL loopback | full rows | 0.931 | 0.994 | 1.126 | 1,838 |
+| PostgreSQL loopback | two columns | 0.530 | 0.555 | 0.849 | 2,817 |
+| PostgreSQL loopback | three posts | 1.778 | 1.960 | 2.383 | 725 |
+| PostgreSQL loopback | aggregate | 0.352 | 0.365 | 0.406 | 5,956 |
+| PostgreSQL delayed relay | full rows | 82.706 | 83.526 | 86.316 | 46 |
+| PostgreSQL delayed relay | two columns | 82.083 | 81.652 | 85.104 | 47 |
+| PostgreSQL delayed relay | three posts | 166.178 | 168.265 | 173.045 | 23 |
+| PostgreSQL delayed relay | aggregate | 80.660 | 80.563 | 83.713 | 49 |
+
+The delayed relay's actual echo RTT p50 was **26.410 ms**, despite the nominal
+20 ms delay; timers and scheduling add overhead. Full-driver `SELECT 1` p50 was
+82.678 ms. Loopback echo p50 was 0.188 ms. Small reversals where ORM appears faster
+under the delayed relay are not evidence of an ORM speedup.
+
+For PostgreSQL, selecting two columns instead of complete users reduced received
+protocol bytes from **27,784 to 4,693** in the probe. Batched relationships returned
+100 parent and 300 child rows in two SQL statements. The ORM's separate eight-client
+relation probe measured acquisition p50 of 5.530 ms for SQLite, 5.212 ms for local
+PostgreSQL and 180.287 ms with the delayed relay. Pool saturation and network costs
+matter more than a single idle-connection probe suggests.
+
+Across three SQLite relationship reads, selected traces recorded **996 raw versus
+8,244 ORM List/backing-List allocations** (`_List` plus `_GrowableList`). These are
+main-isolate traces with tracing enabled, not all-process allocated bytes. They
+identify intermediate collection construction for follow-up review. The measured
+local ORM p50 overhead in that case was 0.089 ms. A future optimization should
+re-run this harness and preserve exact SQL, results, transaction behavior and
+observer semantics before claiming improvement.
+
+The captured report identifies runtime source commit, SDK/OS/CPU, database versions,
+fixture, sample counts and harness hashes. It is one machine/run, without confidence
+intervals or a cross-library comparison. It does not establish AOT, browser or Flutter
+performance. Correctness checks for those platforms have separate evidence.
+
+Use absolute overhead, selected bytes, actual statement counts and measured lease
+waits together. A small local query can have a large percentage overhead while
+remaining short in absolute time. On a delayed connection, protocol round trips
+can dominate; fewer selected columns do not eliminate those round trips. Allocation
+traces identify work worth investigating but do not by themselves justify a cache
+or a new abstraction.
+
+## Direct selection decoding
+
+The separate [selection report](../research/benchmarks/runtime-selection.json)
+captures runtime `d0a8c9a` on the same machine, SDK and database versions. Field
+readers now pass values directly to typed mappers or the requested dynamic Map,
+avoiding a temporary values List for each row. Relationship expansion allocates
+one fixed-length buffer and copies the original row into it. This preserves
+driver-row ownership and adds no cache or dependency.
+
+The workload, relay and VM-profiling helper hashes match the baseline. The main
+harness only adds output-path selection, allowing both reports to be retained.
+Each of the twelve scenario/case combinations has 200 latency and concurrent
+samples per lane and 64 separate acquisition samples. Independent report readback
+confirms identical SQL, parameters, statement/row counts and logical/protocol
+bytes between raw/ORM and before/after. Temporary PostgreSQL schemas were removed.
+
+The selected main-isolate List traces over **three reads** are:
+
+| Backend | Case | Raw before → after | ORM before → after | ORM reduction |
+| --- | --- | ---: | ---: | ---: |
+| SQLite WAL | full rows | 39 → 40 | 1,239 → 333 | 73.1% |
+| SQLite WAL | two columns | 37 → 37 | 885 → 282 | 68.1% |
+| SQLite WAL | three posts | 996 → 996 | 8,244 → 5,220 | 36.7% |
+| SQLite WAL | aggregate | 29 → 29 | 371 → 308 | 17.0% |
+| PostgreSQL loopback | full rows | 3,386 → 3,382 | 4,598 → 3,695 | 19.6% |
+| PostgreSQL loopback | two columns | 2,359 → 2,359 | 3,215 → 2,611 | 18.8% |
+| PostgreSQL loopback | three posts | 10,235 → 10,248 | 17,564 → 14,541 | 17.2% |
+| PostgreSQL loopback | aggregate | 451 → 451 | 803 → 740 | 7.8% |
+
+Counts sum `_List` and `_GrowableList`, including backing arrays. All captured
+traces report zero truncated stacks; the selected-class and isolate limitations
+above still apply. These percentages describe observed List creations, not total
+allocated bytes, retained heap, RSS or throughput.
+
+Normal untraced local latency did **not** establish a speed improvement. Several
+raw-driver timings increased too. All local cases are shown in milliseconds:
+
+| Backend | Case | Raw p50 before → after | ORM p50 before → after | New ORM p95 |
+| --- | --- | ---: | ---: | ---: |
+| SQLite WAL | full rows | 0.111 → 0.127 | 0.160 → 0.170 | 0.267 |
+| SQLite WAL | two columns | 0.055 → 0.057 | 0.075 → 0.075 | 0.164 |
+| SQLite WAL | three posts | 0.728 → 0.806 | 0.817 → 0.907 | 1.099 |
+| SQLite WAL | aggregate | 0.036 → 0.036 | 0.040 → 0.041 | 0.053 |
+| PostgreSQL loopback | full rows | 0.931 → 0.907 | 0.994 → 0.979 | 1.189 |
+| PostgreSQL loopback | two columns | 0.530 → 0.553 | 0.555 → 0.593 | 0.827 |
+| PostgreSQL loopback | three posts | 1.778 → 1.909 | 1.960 → 2.154 | 2.498 |
+| PostgreSQL loopback | aggregate | 0.352 → 0.353 | 0.365 → 0.375 | 0.510 |
+
+Local ORM eight-client throughput was also lower in this capture; all durations
+and throughput samples are retained in the report. Two separate captures cannot
+distinguish small runtime regressions from load, scheduling and JIT variability.
+The supported conclusion is fewer intermediate List allocations, with unchanged
+SQL/result volume and verified correctness, not a latency or throughput gain.
+
+The delayed relay's echo p50 changed from 26.410 to 24.725 ms and full-driver
+`SELECT 1` from 82.678 to 75.129 ms. Relationship raw/ORM p50 changed from
+166.178/168.265 to 162.096/162.396 ms. Transport calibration itself changed, so
+those lower durations cannot be attributed to selection decoding.
+
+The [PostgreSQL adapter](../lib/postgres.dart) still prepares each statement,
+consumes its bound ResultStream and awaits disposal. Inspection of the locked
+`postgres` 3.5.12 implementation shows separate awaited parse and close messages;
+`_PreparedStatement` also queues transaction portals for cleanup in `run()` or
+`dispose()`. Retaining statements while continuing to use `bind()` would retain
+that pending cleanup until disposal. Simply removing disposal is therefore not
+a valid optimization. The adapter currently owns cancellation and awaits control
+cleanup before allowing reuse. A future connection-scoped statement cache or
+protocol change must preserve these lifecycle guarantees and be evaluated with
+the delayed-relay harness. No implicit statement cache is introduced here.
+
+Correctness after this change: 813 native tests with PostgreSQL enabled, clean
+static analysis, and 18 real Chrome scenarios for each of JS and Dart WASM. The
+browser membership scenario additionally covers six mixed field types and
+deferred, ordered mapping. These remain separate from performance evidence and
+do not establish native Flutter behavior.
diff --git a/docs/progress.md b/docs/progress.md
new file mode 100644
index 00000000..b9285702
--- /dev/null
+++ b/docs/progress.md
@@ -0,0 +1,933 @@
+# Implementation status
+
+## Standalone ORM redesign
+
+Implementation branch: `refactor/standalone-orm`. The delivery scope is SQLite (native,
+Dart Web and Flutter Web), PostgreSQL, MySQL 8.4 and MariaDB 11.8. The user has
+authorized commits, push, a Codex-reviewed PR and merge after verification.
+
+Independent values, metadata, driver, raw runtime and typed SQL entrypoints are
+implemented. Generated clients use the SQL layer; the ORM composes a raw
+`SqlDatabase`. Nominal Dart model classes, four-dialect generation, engine-specific
+migrations and the typed project CLI are implemented. Raw migration/catalog
+operations now use `.sql` when starting from an ORM database.
+
+The first complete native regression invocation passed 1119 tests and found five
+failures in older CLI output expectations and new temporary-metadata tests. All
+five have been corrected. The final CLI/import/plan/MySQL migration and SQL review
+run passes 71 tests; the session/transaction/stream/retry/acquisition/watch run
+passes 282 tests, including 18 new borrowed-connection lifecycle regressions.
+A further 176-test PostgreSQL review run passes after bounding initial backend
+PID discovery; four real TCP-proxy regressions reproduce the original hang and
+verify timeout/cancellation before any application write. Forty MySQL driver and
+migration-target checks pass after aligning the minimum MySQL version to 8.4.
+MySQL/MariaDB per-operation timeouts are separately advertised from cancellation;
+140 real driver/database/transaction checks pass. Timeout closes the driver and
+may leave a submitted write outcome unknown; transaction/retry gates stay strict.
+Static analysis is clean. Registry engine parsing, non-atomic plan reporting,
+temporary-history shadowing and session ownership were corrected during review.
+
+Fresh Chrome JS/WASM and Flutter Web JS/WASM (with and without isolation) each
+pass 21 scenarios. Android debug installation, AOT release upgrade and independent
+process reopen pass 4/17/11 checks. Both APKs exclude Web resources. Root and
+Flutter analysis pass. [The final local acceptance record](../research/validation/standalone-redesign.md)
+pins the runtime source and limits. Complete GitHub CI and Codex review of the
+final PR head are the merge gates; earlier captures below retain their revisions.
+
+Linux CI exposed native-asset packaging and capability assumptions in tests.
+The complete run subsequently found 17 remaining interruption assumptions in
+transaction/acquisition/watch tests (1129 passed, 25 skipped); those test cases
+now cover supported behavior or explicit rejection without changing runtime.
+The import AOT fixture now uses a complete `dart build cli` bundle; borrowed
+PostgreSQL tests include URL passwords (48 related checks pass). SQLite
+interruption-dependent cases honor the actual build capability; default Linux
+`sqlite3` 3.6.0 rejects cancellation/deadlines and bounded retries before SQL.
+This limitation is documented rather than replaced with a second SQLite library.
+The complete Linux native stage now passes 1136 tests with 41 capability skips.
+Chrome JS passes 21 scenarios; an exiting-process profile cleanup race in the
+runner is corrected with bounded retries. Browser checks run in an independent CI
+job. Both jobs and final-head Codex review are required before merge;
+[PR #485](https://github.com/medz/dart-orm/pull/485) records their final outcome.
+
+Design: [standalone redesign](../research/standalone-orm-redesign.md).
+Research: [Prisma v8 reassessment](../research/prisma-v8-reassessment.md).
+
+## Unified SQLite integration
+
+The current refactor uses `sqlite.dart` for native and browser connections. Shared
+sqlite3 statement/cursor execution replaces the duplicated implementations.
+`SqliteOptions.persistent(name, nativePath: ...)` keeps storage identity explicit;
+Flutter Web automatically bundles its worker and WASM, and plain Dart exports the
+same verified resources with `dart run orm web-assets`. Startup verifies worker
+build/protocol identity and WASM integrity. Asset names include their content hash.
+
+The real Flutter release builds pass 21 scenarios each in JS, WASM without
+isolation headers and WASM with isolation headers. Plain Dart JS/WASM also pass
+21 each. The repository Flutter example builds for Web, resource export succeeds,
+and static analysis is clean. The complete native suite passes **875 tests in
+09:12**, with real SQLite/PostgreSQL enabled. Five focused native checks and all
+Web configurations pass after finalizing the release artifacts. Negative startup
+checks reject both an old protocol and a different build using the current
+protocol. An Android arm64 asset bundle builds and excludes SQLite Web resources.
+See [validation and limits](../research/validation/sqlite-refactor.md). Android
+device runtime and cross-browser acceptance were not repeated for this change.
+
+## Previous Flutter Web integration research
+
+[The integration study](../research/flutter-web-integration.md) confirms that
+`sqlite3` already supplies Web engine/storage support and shared database APIs.
+A temporary package with Web-only bundled worker/WASM assets passes actual Flutter
+3.47.4 release builds: JS, WASM without isolation headers, and WASM with isolation
+headers each pass the 20 browser scenarios. Long SQL also allows Flutter animation
+ticks to advance. Deep routes under a subpath, page reload recovery and migrations
+are included; [captured evidence](../research/validation/flutter-web-probe.json)
+records actual compilation mode and asset requests.
+
+This is a research probe, not a shipping packaging change. The recommendation is
+package-owned resources and a simpler SQLite entry, with the platform transport
+kept internal. CDN/CSP, cross-browser behavior, multi-tab ownership, hot restart
+and offline deployment still need design/verification. The native Flutter example
+and current manual Web options remain unchanged.
+
+## API and correctness refactor
+
+The comprehensive review of public exports, generation, SQL/decoding, writes,
+session ownership and migration boundaries is recorded in
+[the audit](../research/api-correctness-audit.md). It adds reproduced regressions
+for cross-session subqueries/CTEs, optional-join presence guards, mutation
+validation, concurrent shutdown and cancellation notification. Generated row
+exports, immutable schema lists, target-specific declaration checks and native
+catalog import round-trips are verified. The complete native suite passes
+**872 tests in 10:41**, with real SQLite and PostgreSQL 18.4 enabled. Real Chrome
+JavaScript and Dart WASM each pass **20 checks**, including the new query boundaries.
+Static analysis has no issues. See [final validation](../research/validation/api-audit.md)
+and the [API/mental model guide](api.md).
+
+The full suite includes static generation, build_runner recovery, source/registry
+fingerprints, CLI lifecycle, actual process-exit migration recovery and AOT history
+without source assets. Temporary consumer tests reuse existing SQLite downloads;
+the normal native-asset hook still verifies their hashes. No driver configuration
+or consumer packaging path is substituted.
+
+The previous acceptance records below remain tied to their recorded revisions.
+Android/Apple runtime and performance measurements were not repeated in this
+review. Work stays on `next`, with local commits only and no push/publication.
+
+## Previous migration correction
+
+The single-engine migration correction is implemented. Each registry fixes one
+database engine, including before its first migration; files contain one step list
+and only the selected physical expressions. Mixed histories/connections are
+rejected before migration SQL. PostgreSQL execution checks server 18+, while
+SQLite keeps its 3.35+ driver gate and native rebuild behavior.
+
+The [current validation](../research/validation/migration-targets.md) records 845
+passing full-suite tests and two PostgreSQL crash-test registry configuration
+failures, followed by 21 passing target/recovery tests after correcting those
+fixtures. These are separate invocations. Source-independent AOT migration and
+historical backfill bundles pass; real Chrome JS/WASM each pass 19 checks; the
+public registry and example CLI workflows pass; static analysis is clean.
+Android was not rerun for this correction. Earlier platform captures below remain
+evidence for their recorded revisions.
+
+The Dart schema/migration workflow is implemented and verified. Current snapshots,
+fixed historical migration definitions and static registries are Dart libraries;
+the project entrypoint owns typed connection/rename/conversion inputs. The JSON
+artifact readers and CLI options are removed without a compatibility lane. Named
+SQL generation also emits only Dart and checks freshness against the declaration
+and SQL source. Internal checksum/checkpoint encodings and reports remain JSON.
+
+The earlier [Dart migration acceptance](../research/validation/dart-migrations.json) records
+837 passing tests in the full run and one stale test-fixture path, then a passing
+76-test focused run covering that correction and the final generation changes.
+This is two invocations, not a single all-green full run. The independent AOT bundle
+check passes after deleting consumer Dart sources and build cache; an AOT historical
+backfill additionally proves bounded pause and concurrent exact-once resume.
+At that revision, Chrome JS/WASM each passed 19 checks. Android debug install, release
+AOT APK upgrade and distinct-process restart pass 4/17/11 checks with compiled Dart
+history and no migration JSON assets. The runnable project migration entrypoint
+also passes check/apply/verify/no-replay against a disposable SQLite file.
+
+The common lifecycle in `research/new-dart-orm-design.md` is implemented and
+accepted. The [design acceptance map](acceptance.md) connects each requirement to
+evidence; the [capability review](capabilities.md) states extensions and unverified
+targets. This is a local implementation, with no package publication or push.
+
+Earlier baseline: [835 native tests](../research/validation/native.json) pass
+in one invocation with PostgreSQL enabled. The [usage capture](../research/validation/usage.json)
+passes dependency resolution, generation, the README and teams examples, nine
+query cookbook checks on each backend, migration-chain validation and clean
+analysis. Real Chrome JS and Dart WASM each pass 19
+scenarios, including temporal column precision and extended date/instant ranges.
+An actual Android Flutter application additionally passes 4/17/11 checks across
+legacy installation, AOT release APK upgrade and process restart; see
+[native Flutter evidence and limits](flutter.md).
+
+Editor verification additionally covers real generated APIs at 10/100/1000 models:
+fifteen completion probes with 300 warm samples, twelve diagnostic checks matching
+exact codes/source ranges, and language-symbol rename responses. See the
+[captured protocol measurements and limits](generation.md#editor-completion-diagnostics-and-rename).
+
+The same-driver runtime cost baseline covers SQLite and PostgreSQL, including
+controlled TCP latency, concurrency and separate allocation traces. That baseline
+uses runtime source `94d24fe`; see [measurements](performance.md). Selection decoding
+has since been optimized, with a separate `d0a8c9a` capture confirming fewer
+intermediate List allocations; it does not establish a throughput improvement.
+
+## Completed
+
+- Reset the `next` branch contents, preserving the design research and license.
+- Establish one Dart 3.13 package and local-only commit policy.
+- Single-engine migration histories, flat saved steps, selected schema fingerprints, fixed registry targets, connection/version gates and target-specific destructive-change handling.
+- Dart physical snapshots, fixed migration files, per-file fingerprints, static registries and typed project CLI configuration; generated output cannot overwrite its source declaration.
+- Direct retirement of schema/migration/named-query JSON artifacts, with source-based named-query freshness checks and compiled application migration history.
+- Typed scalar expressions, 2–6-field composable projections and dynamic field maps.
+- Immutable filters, order, offset/limit, count/exists, basic aggregation and mutations.
+- Parameter binding, table occurrence scope checking, explicit default/null changes.
+- Native SQLite worker with verified foreign keys, journal mode and parameter limit.
+- Browser SQLite worker with explicit memory/OPFS storage, exclusive ownership, verified journaling/foreign keys and shared native codecs/functions.
+- Real Chrome acceptance for JavaScript and Dart WASM clients, including persistent reopen, interrupted-transaction recovery and schema upgrades after page reload.
+- Actual Android Flutter acceptance with generated APIs, persistent file storage, old debug APK to new AOT release APK upgrade, distinct-process reopen, watch/rollback behavior and background cancellation/reuse.
+- PostgreSQL driver with a single pool owner, TLS settings and explicit borrowed pools.
+- Transaction lifecycle, rollback, savepoints, pending work checks and query observation.
+- Non-executing SQL/column/key/join/batch inspection and optional acquisition/SQL/decode phase observations with immutable metadata and isolated observer failures.
+- Reproducible same-driver/SQL/result runtime comparisons with latency samples, concurrent throughput, logical/protocol bytes, lease distributions, live heap and separate selected allocation traces.
+- Transaction-wide deadlines/cancellation with native SQL interruption, callback expiry and awaited cleanup.
+- SQLite actual transaction-state reporting, automatic rollback recovery and invalidated-savepoint protection.
+- Conservative server failure classification distinguishing known commit rejection from unknown outcome.
+- Opt-in transaction replay and SQLite COMMIT-only retry with shared attempt/time budgets and cancellable backoff.
+- Analyzer-based record generator, scalar annotations, composite keys, indexes and FK validation.
+- Named SQL files with generated Record parameters/results, dialect-specific methods, native structure checks and stale-output detection.
+- Explicit named-query build_runner assets, CLI generation/checking and shared query/transaction/stream/watch execution.
+- Generated table accessors, named create parameters, byId, typed patches and schema snapshots.
+- Database computed expressions with stored/virtual modes, typed read-only fields, catalog/import metadata and reviewed migrations.
+- Batched and nested relation projections, per-parent SQL window pagination, optional/required relations.
+- Runnable generated many-to-many membership example with role/time payloads, composite keys, bidirectional queries, transactional writes and measured query/row counts.
+- Explicit `relatesTo` query navigation without a database FK, including nonunique/composite/self/inverse edges and unchanged physical snapshots.
+- Correlated relation any/none/every/count; UNKNOWN fails every, and empty sets satisfy it.
+- Dialect DDL, cyclic PostgreSQL FK creation, immutable migration checksums and atomic history.
+- Concurrent migration serialization, read-only planning, column inspection and column drift checks.
+- Runnable generated-client example with migrations, transactions and relationship selection.
+- Atomic upsert with declared unique targets and typed existing/incoming field expressions.
+- Batch inserts with parameter-aware chunks, optional field shapes, returning and all-chunk rollback.
+- Explicit alias joins/self joins, guarded outer-join projections, scalar/IN/EXISTS subqueries.
+- SQL window expressions and pre-execution aggregate/grouping placement checks.
+- SQL UNION/UNION ALL with typed 2–6-field SQL records, scalar operands and post-query mapping.
+- Positional column/codec/nullability validation, scoped branch clauses, CTE exports, streams and set subscriptions.
+- PostgreSQL typed standalone parameter projections and exact integer aggregate decoding.
+- CTEs with typed references to exported SQL expressions, mapped row decoding and nullable exports.
+- Keyset pagination with unique tie breakers, mixed directions, explicit null ordering and versioned cursor transport.
+- Actual generated-API negative type tests and checked codec calls after generic type erasure.
+- Connection leases spanning transactions, with scoped lifetime and explicit discard.
+- Portable schema snapshots; catalog checks for columns, defaults, keys and simple indexes.
+- Existing-database baselines verify declared schema facts before recording immutable history.
+- Read-only catalog import drafts Record declarations, physical-name maps and review reports, followed by the normal generator/baseline workflow.
+- Import preserves supported defaults, identities, composite/unique keys, indexes and named inverse relations; unsupported structures have explicit issues.
+- Signed 16/32/64-bit integer column metadata, native PostgreSQL types and verified SQLite range constraints, independent of value/aggregate codecs.
+- Width-aware generation, catalog import, immutable snapshots, rename/type migrations, identity sequences and historical backfills.
+- Finite exact Decimal values, typed SQL arithmetic, numeric SQLite collation and native PostgreSQL NUMERIC, including keys, relations, aggregates and windows.
+- Decimal generation/import, catalog drift checks, reviewed conversion migrations and exact historical backfill keys.
+- Declared decimal precision/scale, consistent ORM write coercion, exact SQL precision casts, constrained defaults and width-preserving import/migrations.
+- Exact SQL decimal division and six explicit rounding modes, including full finite-range checks and window projections with preserved filtering/grouping/pagination.
+- Exact rounded decimal averages with bounded PostgreSQL component sums, incremental SQLite accumulation and shared window inputs.
+- LocalDate, LocalTime and LocalDateTime with microsecond precision and full finite native PostgreSQL ranges, independent of DateTime and session timezone.
+- Temporal column precision from zero to six digits, matching PostgreSQL rounding in SQLite, with generated writes, explicit value/SQL rounding, default/computed coercion, catalog/import and reviewed precision migrations.
+- Calendar generation/import, SQLite indexed collations, normalized relation keys, typed cursors and resumable historical date-key backfills.
+- Explicit UTC instant storage, offset-equivalent SQLite indexing, strict process-independent decoding and overflow-checked native PostgreSQL DateTime decoding.
+- Reviewed legacy timestamp upgrades preserve captured migration checksums and roll back invalid values or newly equivalent SQLite unique keys.
+- Read-only application startup version checks with explicit compatibility ranges, full history validation and recovery-state rejection.
+- Unmodeled constraints, expression/partial indexes, triggers and policies are reported separately.
+- Reviewable migration diffs, explicit renames/conversions, destructive-change gates and checksum chains.
+- SQLite atomic copy/rebuild with preserved dependency SQL, foreign-key validation and state restoration.
+- PostgreSQL constraint changes resolve actual catalog names, including baselined schemas.
+- Migration CLI: create/check/plan/apply/status, table inspection, schema verification and baselines.
+- Explicit SQLite read-only connections; CLI read operations never create a missing database.
+- PostgreSQL recoverable autocommit steps with boolean pre/postconditions and immutable attempt checksums.
+- Durable per-step progress, exact concurrent-index state checks, explicit INVALID-index repair and CLI visibility.
+- Historical-schema backfills on both databases with bounded primary-key batches, atomic data/cursor commits and completion proofs.
+- Shared batch budgets, lossless composite cursors, competing-runner recovery and committed subscription notifications.
+- Shared migration/baseline session locks use bounded try-lock polling without retaining waiting snapshots.
+- Database cursors with demand-driven batches, per-batch relation loading and scoped stream cleanup.
+- Real SQLite native interruption and PostgreSQL control-connection cancellation with awaited cleanup.
+- Cancellable, bounded connection acquisition with monotonic entry checks and safe late-lease draining.
+- Independent PostgreSQL pool/connection deadlines, with acquisition settings propagated through queries, mutations, batches, streams and watches.
+- Per-statement deadlines, poisoned-transaction protection and atomic cancellation between batch chunks.
+- Explicit cancellation capabilities, borrowed-pool ownership and failed-control connection disposal.
+- To-one JOIN strategy using declared uniqueness, with explicit join/batch choices and cardinality checks.
+- Composite-key batch execution, tuple matching, parameter accounting and nested JOIN/window combinations.
+- Joined optional/required projections preserve row presence, nullable values, CTE exports and cursor decoding.
+- Constant schema codecs retain custom classes, extension IDs, nullable aliases and nested generic/record types.
+- Portable enum text labels, generation-time codec matching and stable imports for separately declared domain types.
+- JSON scalar decoding and explicit SQL-null/document-null distinction across SQLite and PostgreSQL.
+- Typed query subscriptions with commit/savepoint boundaries, relevant-table filtering and declared FK delete effects.
+- Dependency discovery across joins, subqueries, CTEs and batch relations; explicit raw/external-write notifications.
+- Paused subscription coalescing, stale-read suppression, active-query cancellation and driver-wide subscription cleanup.
+- Opt-in build_runner integration with explicit roots, shared generation/formatting and resolver-owned dependency tracking.
+- Asset-based and real-process generation checks, imported metadata invalidation, upstream builder inputs and stale-output cleanup.
+
+## Delivery sequence
+
+1. Typed schema metadata, SQL expressions, projections, query and mutation execution.
+2. Native SQLite worker and PostgreSQL drivers, explicit transactions and savepoints.
+3. Record schema generator, typed table entry points and relationship declarations.
+4. Batched relationship projections, root and per-parent pagination, nested relations.
+5. Migration snapshots, dialect DDL, history/checksums, introspection and drift checks.
+6. Advanced SQL, custom codecs, streaming, observation, Web adapter and capabilities.
+7. CLI, examples, user documentation, real-database and platform acceptance checks.
+
+## Validation
+
+The following paragraphs are the chronological implementation record. References
+to pending work describe that stage; the current acceptance decision and remaining
+extension boundaries are in the final review below.
+
+The research type proof was analyzed and ran with JIT and AOT; JavaScript compilation
+also passed. These checks do not constitute a working ORM or browser validation.
+
+Static analysis is clean. The complete suite passes 740 checks with native SQLite
+and a disposable PostgreSQL 18.4 instance enabled. It exercises generation,
+composite-key source validation, projections, relations, per-parent pagination,
+transactions, migration rollback/history and the generated application client.
+This includes a SQLite catalog regression for nullable non-rowid primary keys
+and three independent CLI process workflows (SQLite lifecycle, SQLite baseline,
+and PostgreSQL lifecycle, including autocommit plans/progress). The full suite
+passes in one invocation. Thirteen recovery checks include two real process exits
+at durable SQL/commit boundaries, INVALID indexes, lock deadlines and concurrent
+runners; committed work is not replayed on resume.
+`dart run example/main.dart` runs successfully against a real in-memory SQLite DB.
+The generated SQLite example also compiles and runs as a native macOS AOT executable.
+Thirty-seven streaming/execution checks cover native cursor fetches, pause/resume,
+early exit, relation loading, deadlines, cancelled writes, failed control connections
+and delayed cancellation races. A batch-cancellation regression was first reproduced
+as a partial commit and now verifies rollback on both databases.
+`test/support/native_execution.dart` additionally compiles and runs as a macOS AOT
+executable, verifying joined records, nullable required values, absent relations,
+cursor consumption, `sqlite3_interrupt`, subsequent SQL and committed query subscriptions.
+The relationship fixture is generated from a record schema with nullable composite
+foreign keys and self-relations. It verifies 1200-key batches, key deduplication,
+per-parent windows, nested JOINs, whole-row absence and root pagination on both
+backends. Generator checks compare committed client code and schema snapshots.
+The domain-type fixture adds 18 real-database checks for extension IDs, custom
+classes, enums, structured JSON, nullable document presence, relations, batches,
+upsert, cursors and schema catalogs. JSON string scalars are decoded without a
+second parse; SQL NULL and JSON null are separately represented, and required JSON
+documents reject SQL NULL. Generator checks cover moved outputs, colliding domain names, nullable
+aliases and invalid annotations. `test/support/codecs/native.dart` passes as a
+macOS AOT program with domain values, relations and streamed cursors.
+Forty-one subscription checks cover both backends, including independent SQLite
+workers and PostgreSQL connections, transactional notification merging, savepoint
+rollback, zero-row writes, multi-level cascade/SET NULL effects, joined CTEs and
+batch relations. They also verify paused-listener cleanup, native cancellation,
+read/invalidation races and re-reading after a real PostgreSQL commit whose
+acknowledgement is deliberately lost. Subscriptions add no browser/Flutter
+acceptance claim.
+Eight asset-builder checks and one real consumer-process workflow verify the
+standard build_runner path, prior-builder inputs, imported metadata invalidation,
+error recovery, explicit root selection and deletion/recreation of generated
+outputs. CLI and builder code/snapshots match. The generator formats in-process.
+The standalone generation benchmark records 10/100/1000-model first builds,
+unchanged builds, watch edits, static analysis and output sizes with pinned
+environment metadata. On the recorded Apple M3 Max run, single-field watch edits
+took 0.52/0.65/2.17 seconds. These are single observations with warm SDK/pub caches,
+not latency percentiles, IDE completion measurements or runtime SQL benchmarks.
+
+Thirty-two set-query checks cover both backends, including repeated positional
+columns, nested set association, operand-local CTE names/order/limits, final DTO
+mapping, outer-join nullability, shared domain codecs, all built-in constant types,
+SQL NULL versus JSON null, scalar subqueries, native streams and committed changes
+from either operand. Negative compilation includes mismatched scalar and Record
+operand types. The native macOS AOT integration also verifies typed UNION Record
+streaming. Whole generated entity/Dart-mapped projections must explicitly select
+SQL `.row` fields before UNION; arbitrary mapper equivalence is never inferred.
+
+Connection acquisition is verified with twenty shared SQLite/PostgreSQL checks,
+three additional PostgreSQL checks (initialization, connection versus queue limits,
+and native pool timeout classification), and a controlled event-loop starvation
+regression using the native SQLite driver. Timed-out mutations, batch transactions,
+sessions and queries never execute after their late leases arrive. Stream
+cancellation, watch recovery, pool PID reuse, resource draining and application
+error propagation are checked. macOS AOT also verifies that an expired queued
+write never runs after the held lease is released. Acquisition controls remain distinct from transaction-wide execution deadlines.
+
+Forty-one transaction-control checks cover SQLite and PostgreSQL plus actual
+concurrent connections and failure-injecting driver wrappers. They verify idle
+and CPU-bound callbacks, active reads/writes/cursor fetches, paused streams,
+borrowed sessions, savepoint cleanup, expired connection acquisition, native
+BEGIN/COMMIT lock waits, automatic rollback, deferred constraint rejection,
+known COMMIT acknowledgement races, lost acknowledgements and failed rollback.
+PostgreSQL serialization failures and deadlocks are produced by real competing
+transactions. SQLSTATE 40003 at COMMIT remains conservatively unknown. Native
+macOS AOT verifies transaction expiry and automatic rollback across a savepoint.
+Twenty-nine retry checks verify explicit opt-in, exact attempt limits, acquisition
+and execution time budgets, cancelled backoff, fresh transaction views, discarded
+failed-attempt notifications, unknown commits and failed rollback. Actual competing
+PostgreSQL connections produce serialization/deadlock conflicts; SQLite workers
+produce WAL busy-snapshot and DELETE-journal COMMIT conflicts. Both callback replay
+and COMMIT-only retry share one finite budget. The acquisition timer preserves its
+own error class rather than inferring the source from an elapsed clock.
+`test/support/native_retry.dart` compiles and runs as a macOS AOT executable against
+two SQLite workers, verifying snapshot replay and COMMIT retry without replaying
+the successful callback.
+
+Nineteen application-version checks cover both databases: exact latest and explicit
+inclusive ranges, unversioned databases, rejected downgrades, old checksum changes,
+missing history, baselines, separate catalog drift, borrowed sessions and invalid
+ranges. PostgreSQL checks use a real partially completed recoverable migration,
+repair/resume and concurrent checkpoint creation during a consistent read snapshot.
+The caller's history list is frozen before asynchronous reads. A read-only SQLite
+file accepts a compatible version without applying migrations. The native macOS
+AOT execution fixture also checks accepted and rejected schema versions.
+
+Fifty-six backfill checks cover both databases: bounded pause/resume, unchanged
+historical JSON/checksums, atomic cursor/data rollback, failed completion proofs,
+compatible and incompatible concurrent writes, competing runners and lost COMMIT
+acknowledgements. Four actual child-process exits at data-write and commit boundaries
+verify that committed chunks are retained and uncommitted chunks are repeated only
+after rollback. Native integer, bigint, text, finite real, boolean, timestamp and
+binary keys survive resume, including composite keys under a reduced parameter
+limit. Additional checks cover ordinary migration grouping, SQLite rebuild/FK
+restoration, old checkpoint-table upgrades, invalid cursors, temporary-object
+shadowing, PostgreSQL row security and inherited duplicate keys. Independent CLI
+processes inspect plans, pause, report progress and finish backfills on both
+databases. Committed chunks notify typed subscriptions, and completion probes
+reject floating-point truthiness. `test/support/native_backfill.dart` compiles and
+runs as a macOS AOT executable, verifying historical declarations, bounded runs,
+concurrent SQLite workers and the application startup version gate. The existing
+native execution acceptance fixture also passes after this change. These are
+correctness checks, not backfill throughput or online availability measurements.
+
+Seventeen catalog-import checks verify both databases, including physical/Dart
+name collisions and escaped identifiers, identities/defaults, composite/self
+relations, unique indexes, read-only SQLite, scoped sessions, excluded unsupported
+types, nullable primary keys, virtual/shadow tables,
+PostgreSQL inheritance and specialized index semantics. Draft declarations pass
+the real analyzer/generator and produce matching schema snapshots. An imported
+client runs against PostgreSQL, and the SQLite client compiles and runs as a macOS
+AOT executable; both preserve existing rows and execute typed relationship queries,
+defaulted writes and SET DEFAULT deletes after a verified baseline. Two additional
+CLI workflows independently import, generate, baseline and verify real databases,
+reject existing output files, preserve missing SQLite files and retain blocking
+issues in review reports. The generator no longer emits invalid empty patch
+parameters for models containing only generated fields. Physical import currently
+uses the exact supported storage mappings documented in `docs/importing.md`;
+Unconstrained NUMERIC now imports as finite Decimal; it is never guessed to contain
+only integers. Broader native types remain part of the active goal.
+
+Twenty integer-width checks cover native signed boundaries, nullable/defaulted
+columns, exact native 64-bit values, wider aggregate results, mixed-width UNIONs,
+relations, transported cursors, generated/imported snapshots and historical
+backfills. Reviewed widening/narrowing migrations run on both databases; overflowing
+existing rows roll back structure and history together. Physical renames and
+identity-width changes preserve generation, including the PostgreSQL sequence
+type. SQLite checks distinguish emitted range constraints from quoted defaults,
+comments and weaker expressions. Analyzer tests reject invalid or repeated widths
+and retain integer-backed domain codec types. The new generated fixture is checked
+for deterministic source and snapshot output. `test/support/integers/native.dart`
+compiles and runs as a macOS AOT executable, verifying boundaries, wider sums,
+relations, overflow rejection and catalog checks. No browser numeric claim is added.
+
+Twenty-nine exact-decimal checks cover canonical values, scientific input,
+finite range limits, signed rounding and independent integer arithmetic, plus
+both databases' typed writes/defaults/patches, comparisons, IN, sorting, distinct
+values, transported cursors, computed CTEs, UNIONs and streaming. Exact sums,
+nullable aggregates, grouping and windows are verified, including a SQLite moving
+frame and intermediate overflow that cancels before a valid final result. A
+numeric key lookup retains SQLite index use; this is a query-plan check, not a
+throughput benchmark. Equivalent numeric spellings match joined/batched relations
+and reject duplicate unique keys. Catalog import/generation, quoted and Unicode
+column collations, default equivalence, historical backfill keys and conversion
+migration rollback run against actual databases. Unsupported drivers reject typed
+decimal SQL before execution. `test/support/decimals/native.dart` compiles and runs
+as a macOS AOT executable, verifying exact values, sorting, aggregate/window
+functions, normalized relation keys and catalog checks. Invalid external SQLite
+text and PostgreSQL special numeric values fail typed decoding; no finite-decimal
+CHECK constraint or cross-client SQLite function installation is claimed. Browser
+acceptance remains open; constrained columns, SQL division/rounding and averages
+are covered by the additional acceptance checks below.
+
+Nineteen precision checks cover signed ties, negative and excess scales, maximum
+precision/scale boundaries, nullable values, defaults, expression writes, wider
+aggregates, SQL casts, CTEs, batches and upserts. Rounded keys participate in real
+foreign-key relationships. Catalogs, snapshots, generated/imported declarations,
+renames, default changes and historical backfills retain column constraints.
+Scale reduction with duplicate rounded keys rolls back structure and history;
+repairing data allows the same migration to resume. SQLite rejects raw values
+that do not fit, detects missing default coercion and retains an explicitly
+disabled trusted_schema setting. The current SQLite binding requires
+trusted_schema ON to evaluate the managed precision CHECK/default functions.
+Generator checks reject invalid/repeated annotations and preserve decimal-backed
+domain types. The precision fixture compiles and runs as a macOS AOT executable.
+Exact SQL averages are covered by the additional acceptance checks below.
+
+Twenty-three division checks compare all signed rounding modes and positive/negative
+scales with exact integer arithmetic. They cover 16383 fractional digits, values
+around rounding ties, nulls, zero divisors, finite-range overflow and enormous
+remainders whose naive intermediate products overflow PostgreSQL NUMERIC. Exact
+defaults reject lost digits. Real queries combine division/rounding with grouped
+aggregates, windows, HAVING, DISTINCT, ordering, pagination, outer joins, CTEs,
+UNIONs, correlated subqueries and per-parent batched relation pagination. Window
+expressions retain frame/partition/order identity when referenced through CTEs.
+Volatile PostgreSQL operands are evaluated once each; failed expression writes
+roll back their transaction. The updated decimal fixture compiles and runs as a
+macOS AOT executable, including exact SQL/window division and configurable rounding.
+PostgreSQL uses scalar quotient/remainder stages and an additional projection for
+window operands; native arithmetic throughput is not implied.
+The reproducible decimal benchmark separately records native AOT 10000-row
+read/divide/round/window queries on SQLite 3.51.0 and PostgreSQL 18.4. Its raw
+report is `research/benchmarks/decimal-division.json`; methodology and medians
+are in `docs/decimals.md`. This is a small single-client end-to-end cost probe,
+not the complete runtime performance acceptance or a high-precision stress benchmark.
+
+Twenty-three average checks cover exact integer fractions, empty/all-null/constant
+inputs, signed ties and every rounding mode, maximum fractional scale and explicit
+final-result overflow. Means remain valid when an intermediate total exceeds the
+finite NUMERIC range, including cancellation between extreme values. Real queries
+cover grouping, HAVING, unique-input CTEs, UNIONs, streaming, partitions, mixed
+windows, DISTINCT results, pagination and windows over grouped sums. Correlated
+averages update fields; failed exact rounding rolls back the containing transaction.
+Per-parent relation windows retain limits. PostgreSQL sequence tests prove one
+evaluation per contributing input/order row, including repeated source values;
+SQLite moving-frame tests remove values, reset empty frames and reject varying
+rounding policies. Illegal aggregate assignments and nested windows fail before
+execution. The updated decimal AOT fixture verifies ordinary and running averages.
+The expanded native benchmark records 10000-input-row averages and running
+averages in `research/benchmarks/decimal-average.json`, together with read/divide/
+round controls. It uses the same bounded single-client method and records returned
+row counts separately; it does not establish concurrency or large-coefficient cost.
+
+Twenty-four local temporal checks verify Gregorian era/leap boundaries, random
+full-range ordinal round trips, finite PostgreSQL endpoints, microseconds and
+24:00. Real SQLite/PostgreSQL checks cover generated writes, defaults and null
+patches, ordering/min/max/windows/grouping, CTEs, UNION, streams, equivalent
+relation keys, unique indexes, cursor transport, imported declarations and
+historical date-key backfill recovery. Reviewed text-to-time conversion rejects
+equivalent unique keys and rolls back. A reproduced PostgreSQL default comparison
+regression now retains expression casts that discard time. Invalid external dates
+and infinities fail typed decoding without damaging the connection. Borrowed
+PostgreSQL pools explicitly opt into the configured calendar registry; the
+unconfigured path rejects temporal queries before execution. A second negative
+compilation check rejects five calendar/instant/string mismatches.
+
+`test/support/temporals/native.dart` compiles and runs as a macOS AOT executable,
+covering endpoints, calendar order, bounded streams, equivalent relation keys and
+catalog/default verification. These checks do not establish browser behavior or
+temporal query throughput. Column precision, calendar SQL arithmetic and timezone
+conversion are still pending. The local-type checks are distinct from the UTC
+instant corrections verified below.
+
+Twenty UTC instant checks reproduce and correct the prior SQLite microsecond
+ordering and process-timezone decoding failures. Native SQLite/PostgreSQL tests
+cover common DateTime endpoints, microsecond round trips, offset-equivalent
+predicates/unique keys/relations, indexed lookups, grouping/windows/CTEs/UNION,
+streaming, cursors, imported DateTime declarations, literal defaults and expression
+cast drift. Instant-key backfills resume across BC and sub-millisecond boundaries.
+Out-of-DateTime PostgreSQL values retain raw text and fail typed decoding without
+integer overflow or connection damage.
+
+The captured `test/support/instants/m0001_legacy.dart` was emitted using commit
+`00853b4`. Its original checksum is asserted after decoding with the current
+migration reader. Both databases upgrade it through a reviewed timestamp-to-instant
+change; SQLite tests prove rollback on equivalent keys and invalid calendar text.
+The new instant storage tag leaves old snapshot/DDL meaning unchanged. Native
+drivers use one `temporal` capability for local calendar values and UTC instants;
+borrowed PostgreSQL pools require the configured registry before opting in.
+
+`test/support/instants/native.dart` passes JIT in a Shanghai-timezone subprocess
+and as a compiled macOS AOT executable under UTC, Asia/Shanghai and America/New_York.
+It checks UTC defaults, local DateTime input conversion, microsecond sorting and
+relations. These checks do not prove browser precision, timezone-name resolution,
+column precision policies or temporal throughput.
+
+Twenty-four named SQL checks cover deterministic generation, bound/repeated/nullable
+parameters, injection strings, SQL quotes/comments, typed projections, CTEs, UNION,
+scalar subqueries, Decimal/calendar/instant codecs, streaming, transaction rollback,
+explicit watch dependencies, and native structure failures. Seven additional
+invalid API uses fail Dart analysis, including wrong result types and calling a
+PostgreSQL-only query on SQLite. The CLI refuses stale generated files and opens
+SQLite checks read-only without creating missing database files.
+
+SQLite EXPLAIN and PostgreSQL PREPARE checks do not execute the application SELECT;
+throwing expressions and an unchanged PostgreSQL sequence verify that boundary.
+PostgreSQL prepared statements are deallocated after storage checks. Result
+nullability, value ranges and custom codec semantics remain explicit declarations
+with runtime decoding, rather than claimed database inference.
+
+The real build_runner build/watch process also tracks named SQL assets and imported
+enum changes, recovers from SQL parameter errors, and removes both query outputs
+when their source is deleted. The native named-query fixture compiles and runs as
+a macOS AOT executable with SQLite. See
+`docs/named-sql.md` for the API and validation limits.
+
+Sixteen browser acceptance scenarios pass in Chrome 153 with a JavaScript client,
+and the same sixteen pass with a Dart WASM client. Both use a separately compiled
+JavaScript database worker and the pinned sqlite3 3.6.0 WASM asset. They cover
+memory migrations/catalogs, FK enforcement, generated records and relations,
+rollback/savepoints/transaction lifetime, bounded cursors, watch snapshots, exact
+BigInt/Decimal/blob/calendar transport, unsupported interruption, responsive UI
+events during a long query, bounded startup failures and exclusive OPFS ownership.
+Committed rows survive closing/reopening and an actual page reload while a second
+transaction is still open. Reload recovery discards that transaction, passes
+integrity_check, and applies the next schema version without losing prior rows.
+
+Browser acceptance reproduced two numeric differences: integral doubles can be
+mistaken for unsafe integer parameters, and epoch-microsecond arithmetic loses
+precision for remote DateTime values. Explicit SqlReal binding and component-based
+instant decoding preserve their intent and precision in both compilation modes.
+Floating keyset cursor tokens preserve their value and stable tie breaker.
+Checks include BC microseconds and DateTime's upper boundary. Two additional real
+native database checks verify SqlReal floating storage on SQLite and PostgreSQL.
+The native UTC instant AOT fixture is revalidated after sharing SQLite functions
+with the web worker. Captured browser results are in
+`research/validation/browser.json`; setup and limitations are in
+`docs/sqlite-web.md`. These correctness checks do not measure throughput or certify
+Safari, Firefox, Flutter embedding, IndexedDB or a shared multi-tab service.
+Statement interruption remains explicitly unsupported by this web driver.
+After the floating-cursor correction, all 54 native query/floating-parameter
+checks pass again, as do both complete browser runs and static analysis.
+
+The native full suite passes in one invocation with PostgreSQL enabled. macOS runs
+test files serially because separate Dart CLI startups can concurrently rewrite
+and codesign the shared SQLite native-asset cache before application code starts.
+Explicit concurrent database operations inside tests remain enabled. Browser
+acceptance commands run separately from the native suite.
+
+Twenty-four unconstrained-relation checks cover real SQLite/PostgreSQL catalogs,
+missing/nullable targets, nonunique cardinality, per-parent pagination, self and
+inverse navigation, correlated predicates, streaming, transactions and watch
+dependencies. The declaration adds no FK, index, uniqueness promise or cascade.
+Adding a real FK over dangling data fails and rolls back; repairing rows permits
+the same reviewed migration to proceed. Removing it preserves rows and permits
+unmatched references again.
+
+Seven generator checks distinguish query navigation from physical constraints
+and reject invalid selectors, types, codecs, names and referential actions.
+Five additional invalid generated API calls fail static analysis. Existing FK
+fixtures remain byte-for-byte deterministic. Browser JS and Dart WASM acceptance
+also covers generated query-only relations with single and composite REAL keys.
+This reproduced a missing floating binding tag in relationship batches; grouping
+now retains comparable storage values and binding restores SQL floating intent.
+See `docs/relations.md` for declaration and integrity semantics.
+The complete native suite passes all 703 checks in one invocation after these
+changes, with PostgreSQL enabled. Both complete browser runs and static analysis
+also pass. The design acceptance map records the remaining product gates.
+
+Seventeen CHECK checks cover generated named/unnamed constraints, SQL NULL,
+native write failures, import and baseline without replacing rows, duplicate
+constraints, drift, casts/precedence, missing/type-changed columns and SQLite
+Unicode identifiers. Add/change/remove migrations validate old data and roll back
+history on failure; explicit renames preserve incoming references, indexes,
+views and SQLite triggers. Unclaimed checks still block SQLite rebuilds.
+PostgreSQL unvalidated, NO INHERIT and NOT ENFORCED constraints stay unmanaged;
+verification plans but does not execute volatile row expressions.
+
+The generator additionally rejects dynamic/empty CHECK SQL, empty names and
+duplicate names. CLI inspection exposes names and expressions. Older snapshots
+without checks preserve their JSON/checksum representation. CHECK SQL is trusted,
+uses physical names and may have backend overrides; PostgreSQL comparison has
+planning cost, and checked SQLite renames may copy a table twice. These boundaries
+are documented in `docs/checks.md`.
+
+The complete native suite passes 721 checks in one invocation, with PostgreSQL
+enabled, after updating an old integer-test assertion for the newly recognized
+CHECK catalog category. Static analysis reports no issues. Real Chrome JS and
+Dart WASM runs each pass 15 scenarios, including generated CHECK enforcement,
+atomic constraint migration failure/retry and persistent upgrades. The browser
+report records both runs; these are correctness checks, not performance results.
+
+Seventeen client-default checks cover real SQLite/PostgreSQL creation, typed
+domain IDs, nullable values, DateTime constructors, optional static-method
+arguments, generic factories and const function references. Explicit values/null
+and database DEFAULT bypass the corresponding factory. Prepared inserts and
+batches call each omitted factory once and retain values through compilation,
+execution and conflict clauses. Updates do not apply insert defaults; database
+rollback does not undo Dart side effects. Explicit DEFAULT on a client-defaulted
+identity retains each backend's native sequence behavior.
+
+Generation and moved-output analysis do not execute application factories.
+Generator negatives reject incompatible/async scalar results, erased domain
+types, required arguments, private/nonconstant references and repeated annotations.
+Four invalid generated create calls fail static analysis. Snapshots and imports
+contain no client factories; physical defaults and migration checksums remain
+separate. Tables without client factories take a direct insertion path, while
+other tables cache their default-bearing columns. See `docs/defaults.md`.
+
+The complete native suite passes 740 checks in one invocation with PostgreSQL
+enabled, and static analysis reports no issues. Both real Chrome compilation
+modes pass 16 scenarios, adding client omission versus explicit null and prepared
+batch behavior. The browser schema snapshot itself is unchanged by adding a
+client factory. No throughput measurement is claimed by these correctness runs.
+
+Nineteen computed-column checks cover SQLite and PostgreSQL stored/virtual CRUD,
+nullable results, batch/conflict returning, generated relationship keys, quoted SQL,
+catalog/import roundtrips and drift. Existing rows survive add/drop, expression and
+result-type changes, stored-to-ordinary materialization, renamed CHECK expressions,
+indexes, incoming references and views. Invalid recomputation rolls back rows,
+schema and migration history. Decimal computation retains precision casts through
+import and generation. Ten invalid declaration cases and seven invalid generated
+API uses fail source/type checks; low-level copy/backfill maps reject computed
+targets. CLI inspection returns computation SQL and storage mode.
+
+The implementation uses `ReadField` for computed results and excludes those
+fields from generated creation/patch inputs. Native PostgreSQL mode/dependency
+limits remain explicit; automatic diff requires reviewed replacement plans for
+mode conversions it cannot emit natively. Renamed computed SQLite tables may
+require two copies. See `docs/computed.md` for these costs and migration limits.
+The complete native suite passes 761 checks in one invocation with PostgreSQL
+enabled, and static analysis reports no issues. Real Chrome JS and Dart WASM each
+pass 17 scenarios, including computed updates and migration recomputation alongside
+the existing OPFS recovery/upgrade scenarios. The captured browser report records
+both runs; these do not establish throughput or native Flutter behavior.
+
+Eighteen many-to-many checks exercise the generated `example/teams` schema against
+SQLite and PostgreSQL. Memberships carry an enum role and UTC joining time, with
+two foreign keys and a composite primary key. Forward/reverse pagination returns
+only requested associations; root pagination and empty results remain independent.
+Nested team rosters deduplicate shared keys, parameter limits trigger bounded
+chunks, and correlated predicates/counts remain in one statement. Tests assert
+actual statement counts and fetched-row volume alongside payloads and endpoint
+identity. Transactions roll back partial endpoint/association writes; composite-key
+conflicts preserve joining times, unlinking preserves endpoints, cascades remove
+only affected memberships, and watches track committed payload/endpoint changes.
+
+Six invalid generated API uses fail analysis, covering composite keys, enum
+payloads, result shapes and nonexistent implicit graph writes. The new example is
+part of deterministic generation checks and runs directly, reporting two SQL
+statements returning one root and two association rows. The targeted native
+invocation passes 54 checks (many-to-many, generator and types), and static analysis
+reports no issues. This stage adds examples and acceptance coverage over the
+existing runtime; the last full-suite run remains the 761-check invocation above.
+Real Chrome JS and Dart WASM each pass 18 scenarios. Both exercise the same teams
+schema, checking association payloads, per-parent limits, two-statement reads,
+transaction updates and endpoint cascades. The browser report retains both runs.
+
+Twenty-seven new plan/observation checks pass against real SQLite and PostgreSQL.
+Inspection uses existing statement compilers, without acquiring a connection,
+decoding fabricated rows or invoking result mappers. It exposes root and one-key
+child SQL templates, projection/presence/key slots, joins, read dependencies,
+per-parent pagination and composite-key chunk capacity. Template count is distinct
+from data-dependent execution count. Bound values are omitted; literal SQL text
+is retained. Raw dependencies stay explicitly opaque.
+
+Optional acquisition and decoding hooks propagate into sessions, transactions
+and savepoints. Tests cover real pool/lease waiting, timeout/cancellation and
+late-lease draining, SQL versus mapper failures, nested row grouping, cursor
+batches and returning writes. Observer exceptions preserve commits and original
+errors. Hooks omitted means no observation events or measurement Stopwatches;
+inspection is only constructed when requested. These phase measurements exclude
+some client work and do not isolate server CPU or provide trace correlation IDs.
+See `docs/observability.md` for the exact scope and runnable example.
+
+Static analysis passes. The updated teams example executes two SQL statements,
+returns one root/two child rows and reports one acquisition/two decode batches.
+The full native invocation passes 807 checks with PostgreSQL enabled. Real Chrome
+JS and Dart WASM each pass 18 scenarios, including non-executing plan inspection,
+one acquisition and child/root decode observations for generated memberships,
+alongside OPFS persistence, reload recovery and upgrades. The captured browser
+report contains both runs. This establishes behavior, not throughput or allocation
+cost; native Flutter and the remaining acceptance gates are still open.
+
+The runtime cost harness completes four workloads on SQLite WAL, local PostgreSQL
+and a delayed TCP relay, retaining 200 raw/ORM samples for both paired latency and
+eight-client throughput. Probes verify exact SQL/parameters, result shapes and row
+volumes; PostgreSQL protocol bytes and SQLite logical JSON byte counts have distinct
+labels. Independent echo calibration measured 26.410 ms p50 for the nominal 20 ms
+delay. This is a local controlled-latency experiment, not a remote-server deployment.
+
+Separate processes measure live isolate-group heap/RSS and selected main-isolate
+allocation traces. The SDK's current `accumulatedSize` implementation reports live
+size, so the harness does not misrepresent it as total allocation. Timing processes
+have hooks, VM service and profiler disabled. Captured tool hashes, sample counts,
+SQL/parameter equality and result volumes were independently read back. Analysis
+reports no issues; no runtime source changed in this stage, so the 807-test and
+JS/WASM correctness runs above remain the runtime baseline.
+
+The results identify intermediate List construction and PostgreSQL protocol
+round trips as concrete optimization candidates. There is no new performance
+percentage guarantee or claim of superiority over another ORM; detailed numbers,
+scope and reproduction commands are in `docs/performance.md`.
+
+Selection decoding now binds field readers once and passes their results directly
+to each typed mapper. Dynamic field maps also avoid an intermediate value list.
+Related rows are expanded into fixed-length buffers with one copy, retaining
+separate storage from driver rows. Public API, SQL, result shapes and mapping order
+remain the existing contract. Six new backend checks cover all two-to-six-field
+arities, repeated columns, deferred/ordered evaluation, streaming, first-error
+propagation and dynamic field snapshots/nulls. The focused selection, relation,
+observation, inspection and UNION invocation passes 93 checks. The full native
+invocation passes 813 checks with PostgreSQL enabled, and analysis reports no
+issues. Real Chrome JS and Dart WASM each pass 18 scenarios; the teams scenario
+additionally checks a six-field mixed-type projection and deferred/ordered mapping.
+The browser report retains both runs. The separate `runtime-selection.json` cost
+capture preserves the original baseline, retaining 200 timing/concurrency samples
+per lane and 64 acquisition samples. All twelve scenario/case combinations retain
+identical SQL, parameters, row volumes and logical/protocol bytes. Three SQLite
+relationship reads reduce selected List/backing-List traces from 8,244 to 5,220;
+local PostgreSQL reduces them from 17,564 to 14,541. Normal latency and throughput
+do not establish a speed improvement: some timings increased alongside raw-driver
+controls, and relay calibration changed between runs. The report records those
+limits rather than attributing timing changes to decoding.
+
+PostgreSQL protocol lifecycle review confirms separate awaited prepare/dispose
+work and pending portal cleanup in the pinned driver's Statement implementation.
+Caching statements while retaining the current bind path cannot just omit
+disposal; cancellation, portal release and connection reuse must stay valid.
+The current adapter deliberately retains its verified cleanup behavior. The
+measured round-trip cost and scope are documented in `docs/performance.md`.
+
+Temporal precision now spans declarations, generated/manual columns, immutable
+snapshots, SQL assignments and value/expression operations. Default and explicit
+six-digit declarations retain the prior canonical snapshot and migration checksum.
+SQLite uses managed coercion/functions and CHECKs; PostgreSQL uses native type
+modifiers. Runtime rounding uses day-local microseconds to preserve extended dates
+on JS without overflowing a total timestamp count. Tests cover all seven precisions
+around the PostgreSQL epoch, BC dates, extended timestamp/instant limits, nullable
+values, defaults/computed columns, CTE/grouping/streams, batch/upsert and rounded
+relation keys. Import roundtrips preserve metadata and avoid duplicate wrappers.
+Reviewed narrowing and rename can detect merged unique keys, rolling back schema,
+data and history before a successful retry.
+
+The new 21-check suite and the 17-check catalog import suite pass together. The
+full native invocation then passes 834 checks with PostgreSQL enabled. Static
+analysis passes. Real JS and WASM each pass 19 browser scenarios, including the
+new precision worker scenario and existing persistence/reload upgrades. The
+captured browser report includes both runs; no native Flutter claim is added.
+
+## Editor protocol capture
+
+`tool/benchmark_editor.dart` launches the installed Dart 3.13.3 Analysis Server in
+isolated consumer packages against runtime `7eaab3b`. The checked report is
+`research/benchmarks/editor.json`; it retains harness hashes, every warm sample,
+startup/readiness costs, diagnostic ranges and applied rename edits. Independent
+readback checks all hashes, nearest-rank quantiles, current error ranges and rename
+edit counts. Final consumer analysis passes at all three scales. Root static
+analysis also passes; runtime sources are unchanged from the 834-native-check and
+19-per-browser-scenario capture above.
+
+At 1000 models, warm table-entry completion is 11.572 / 17.094 ms p50 / p95;
+query-field completion is 0.780 / 0.850 ms. Initial project readiness is 3.405 s,
+and the query-field probe has a separate 128.488 ms opening/diagnostic wait. These
+are stdio protocol observations with twenty warm samples per probe, not complete
+GUI latency or a declaration-frontend comparison.
+
+Record field rename returns null. Primary-constructor and table fields update
+their declaration and typed reference; typedef rename updates the alias and its
+two references. Rename probes run in a separate clean server: same-session class
+field rename after diagnostic recovery stalled during harness development and
+is not proven reliable here. A valid Dart arithmetic index selector passes CLI
+analysis but the generator rejects it with a source offset, demonstrating the
+boundary between Dart and ORM-specific rules. This closes the measured LSP slice,
+not the full three-authoring-frontend experiment or whole-product goal.
+
+## Declaration-form comparison
+
+`tool/compare_authoring.dart` now executes the design's User/Post/Profile/Follow
+experiment using actual Record, primary-constructor and typed table declarations.
+Experimental adapters resolve each input, preserve field metadata and map it to a
+common Record schema before using the unchanged production generator. The base,
+field-type edit and physical-name-preserving field rename each produce identical
+canonical source, generated client and physical snapshot across the three forms.
+Four composite FKs, compound keys/uniqueness, identity/default/nullability, index
+order and CHECK contents are verified independently from the report.
+
+All forms compile the same generated create/patch and nested relation consumer.
+The six stale-consumer checks fail after type edits/renames and pass after their
+references/types are repaired. Fourteen negative cases locate Dart, generator or
+adapter errors in original source; constructor logic and custom table codecs are
+rejected instead of silently lost. Class/table schema rename updates the field and
+typed constraint reference through real LSP edits. Record field rename is manual.
+
+The captured model declarations occupy 487 / 585 / 1,574 bytes and 24 / 24 / 43
+formatted lines respectively. These are fixture observations, not a universal
+Record superiority claim. Stage timings have fixed-order JIT/cache bias and are
+not a frontend speed comparison. The [report and interpretation](authoring.md)
+preserve the distinction between schema-only adapters and nominal runtime rows.
+Root static analysis passes. Runtime sources remain unchanged; this work does not
+claim additional database or native Flutter validation.
+
+## Native Flutter APK upgrade acceptance
+
+The Android application and host runner are now captured in
+`research/validation/flutter.json`. Flutter 3.47.4/Dart 3.13.3 loads SQLite 3.53.4
+on an isolated API 35 arm64 emulator. Version code 1 writes two records; version
+code 2 is installed with `adb install -r`, adds the new field/relationship, retains
+the original physical column and verifies existing values down to microseconds.
+The release application checks generated writes/projections, transaction rollback,
+commit-driven watch delivery, native cancellation and subsequent worker reuse.
+An independently restarted release process verifies three persisted rows and the
+comment, unchanged migration checksums, no migration replay and read-only reopen.
+
+The three phases pass 4/17/11 assertions. A two-million-row recursive sum completes
+while main-isolate timer and Flutter animation callbacks advance (15 and 7 in the
+final capture). These are progress observations, not an FPS or throughput claim.
+Source/APK/screenshot hashes and version/history/row continuity were independently
+read back. The stable screenshot was visually inspected. Initial oversized log
+chunks were truncated by Android; bounded chunks and a fresh complete run resolved
+the report transport issue. ORM runtime source is unchanged. Root analysis and
+the bundled migration chain check pass; the prior 834-test native run and 19+19
+browser scenarios remain separate runtime evidence.
+
+This closes the Android native Flutter gate, not physical-device, Apple-platform
+or power-loss acceptance. Reproduction and exact scope are in [Flutter](flutter.md).
+
+## Final acceptance review
+
+The final native run passes 835 tests in 7 minutes 44 seconds on Dart 3.13.3,
+SQLite 3.53.4 and PostgreSQL 18.4. The exact log, command and changed-source hashes
+are saved in [native validation](../research/validation/native.json). Subsequent
+documented usage and analysis passed without modifying the tested runtime.
+
+- Advanced queries are documented with an executable cookbook: filters, joined
+ ordering, relation counts, grouped CTEs, windows, subqueries and versioned
+ nullable cursors pass nine checks on each real backend.
+- Catalog review now preserves PostgreSQL policy roles/command/mode/expressions
+ and enabled/forced RLS flags. Import/baseline leave them unchanged. Actual
+ triggers on both backends continue to execute after import and verification.
+- Type, backend and migration behavior are reconciled against design §§5 and
+ 10–12 in [capabilities](capabilities.md). Calendar SQL arithmetic, timezone-rule
+ conversion and additional native extensions remain outside the implemented
+ typed API; the design does not specify that function family.
+- Native Flutter has direct Android debug → release upgrade and restart evidence.
+ Browser JS/WASM have separate worker/OPFS evidence. Neither capture certifies
+ every platform or every native server test on that platform.
+- Generation, editor and runtime cost reports retain their actual sample scopes
+ and historical source revisions. The same-session editor rename timeout and
+ checked server-restart recovery are retained as an explicit limitation.
+- The documented onboarding, migration assets, examples and static analysis pass;
+ [acceptance](acceptance.md#final-lifecycle-audit) maps the complete usage lifecycle.
+
+To-one projections join by default when declared keys prove uniqueness; otherwise
+they batch and check cardinality. Collections use explicit parameter-aware batches.
+`verifyColumns` checks column names/types/nullability, integer widths, decimal precision/scale, SQLite collations and computed expressions/modes. `verifySchema` additionally compares defaults,
+keys, row CHECK constraints and simple indexes; its `unmanaged` objects require separate review.
+Ordinary migration batches are atomic. Explicit backfills use durable per-step
+checkpoints and short data transactions on both databases. General recoverable
+autocommit SQL remains PostgreSQL-only; SQLite rejects `CheckedSql`. These are
+documented backend boundaries, not silently substituted behavior.
+
+The full suite includes 52 shared SQLite/PostgreSQL query checks, 20 generated
+client/migration integration checks, 29 source generation checks, five codec
+regressions, 19 migration evolution/catalog checks, 13 recovery checks, three CLI
+workflows, 37 streaming/execution checks, 28 relation strategy checks and three
+negative compilation checks covering 29 invalid API uses, plus 18 domain-codec
+integration checks, 41 subscription checks, eight asset-builder checks and one
+build_runner process workflow, plus 32 real-database set-query checks and 24 acquisition checks, plus 41 transaction-control checks, 29 retry checks, 19 application-version checks, 56 backfill checks, 18 catalog-import checks, two import CLI workflows, 20 integer-width checks, 29 exact-decimal checks, 19 decimal-precision checks, 23 decimal-division checks and 23 decimal-average checks, plus 24 local temporal checks, 20 UTC instant checks, 24 named SQL checks, two explicit floating-parameter checks, 24 unconstrained-relation checks, 17 CHECK-constraint checks and 17 client-default checks.
+
+Nineteen computed-column checks and additional generation/type checks are included
+in the current aggregate above.
+
+## Environment
+
+Use the standalone SDK if the Flutter launcher tries to update its cache:
+`/Users/seven/workspace/flutter/bin/cache/dart-sdk/bin/dart`.
+
+On 2026-09-15 the installed Flutter cache reports 3.47.4 stable with Dart 3.13.3.
+Xcode reports 27.0 (27A266a), but `xcodebuild -license check` exits 69 and explicitly
+reports that its license has not been accepted. Apple-platform Flutter verification
+needs the user's own license review/acceptance and any remaining Xcode initialization.
+No license was accepted on the user's behalf; other development can continue.
+
+The installed Android SDK and API 35 arm64 image were used to create a separate
+temporary AVD without modifying the user's existing AVD. Both APK builds and the
+three application phases succeeded. Flutter's build provisioned its NDK
+28.2.13676358 through the existing SDK setup; no interactive license acceptance
+was performed. Android acceptance does not depend on resolving the Xcode state.
diff --git a/docs/queries.md b/docs/queries.md
new file mode 100644
index 00000000..04ac6285
--- /dev/null
+++ b/docs/queries.md
@@ -0,0 +1,228 @@
+# Queries
+
+`select` chooses SQL expressions and decodes their values. A scalar expression
+returns its Dart type; `(u.id, u.email).map(...)` constructs a named Record or DTO
+after reading the selected columns. `(u.id, u.email).row` returns a positional
+`(int, String)` Record with no custom mapping. SQL records support 2–6 fields.
+
+`query.map(...)` maps the already selected Dart result. It does not create SQL
+columns, and its properties are not usable in SQL filters or ordering.
+
+Run the [cookbook](../example/queries.dart) with `dart run example/queries.dart`.
+It checks nine combined query/schema scenarios on an in-memory SQLite database.
+Set `ORM_EXAMPLE_POSTGRES` to a disposable local PostgreSQL URL to run the same
+checks there. That example explicitly disables TLS for local development, creates
+a uniquely named schema and removes only that schema in `finally`.
+
+## Filters, results and ordering
+
+Build a query with normal Dart control flow. Builder calls return new query
+values; terminal calls execute them:
+
+```dart
+var query = db.users.where((u) => u.email.like('%@example.com'));
+if (minimumScore != null) {
+ query = query.where((u) => u.score.gte(minimumScore));
+}
+final emails = await query.orderBy((u) => [u.id.asc()])
+ .take(20).select((u) => u.email).get(); // List
+```
+
+Use `.eq`, `.and` and `.or` to construct SQL predicates. `.isNull()` and
+`.isNotNull()` test SQL NULL; `.eq(null)` is available only on a nullable field.
+An empty `isIn([])` is false. Other NULL-containing membership expressions retain
+SQL's three-valued logic, not Dart collection semantics. Values are bound as
+parameters. `like` treats `%` and `_` as SQL wildcards.
+
+`get()` returns a list, `first()` returns the first value or null, and `single()`
+requires exactly one result. `count()` and `exists()` issue dedicated SQL. Add
+explicit ordering when the first row or page must be deterministic. Use
+[keyset cursors](#keyset-pagination) for changing large datasets;
+`skip`/`take` provide offset/limit pagination.
+
+## Keyset pagination
+
+Choose distinct root-table columns with a declared unique tie breaker. Nullable
+columns require explicit NULL ordering:
+
+```dart
+final first = await db.users
+ .orderBy((u) => [u.nickname.asc(nulls: .last), u.id.asc()])
+ .take(20).get();
+if (first.isNotEmpty) {
+ final last = first.last;
+ final token = db.users.cursorToken((u) => [
+ u.nickname.cursor(last.nickname, nulls: .last), u.id.cursor(last.id),
+ ]);
+ final next = await db.users.seekToken(token,
+ orderBy: (u) => [u.nickname.asc(nulls: .last), u.id.asc()],
+ ).take(20).get();
+}
+```
+
+`seekAfter` accepts the same typed cursor terms directly. `cursorToken` transports
+their values losslessly and `seekToken` validates the format version, table,
+ordering and codecs. Keep the original filters when constructing subsequent
+pages. A cursor is pagination input, not an authorization token or a frozen
+snapshot. Joins, grouping, DISTINCT, CTE/set results, offset and non-column
+ordering do not have the required table-key proof and are rejected.
+
+## Join and order by related fields
+
+Use a typed alias when a related field participates in root ordering or a flat
+projection. This example uses the [generated example schema](../example/schema.dart):
+
+```dart
+final author = usersTable.alias();
+final rows = await db.posts
+ .join(author, on: (p, a) => p.authorId.equals(a.id))
+ .orderBy((p) => [author.fields.email.asc(), p.id.asc()])
+ .select((p) => (p.title, author.fields.email).row)
+ .get(); // List<(String, String)>
+```
+
+For `leftJoin`, wrap a possibly absent selection with
+`author.optional(author.fields.email)` and compose it with `.map(...)`; an
+unguarded non-null field is rejected before SQL. `author.isPresent` can test
+the joined row's presence independently of its nullable values. Aliases cannot
+be reused across unrelated query scopes or referenced before their join.
+
+To order by a collection count, use
+`db.users.orderBy((u) => [u.posts.count().desc(), u.id.asc()])`. This compiles a
+correlated count without loading posts. Normal nested results still use
+[relationship selections](relations.md) and their explicit loading strategies.
+
+## Grouping, subqueries, CTEs and windows
+
+```dart
+final totals = db.posts.groupBy((p) => [p.authorId])
+ .having((p) => p.id.count().gt(1))
+ .select((p) => (p.authorId, p.id.count()).row)
+ .asCte('author_totals');
+final active = await totals.query
+ .orderBy((c) => [c.ref((p) => p.authorId).asc()]).get();
+
+final ranks = await db.posts.orderBy((p) => [p.id.asc()])
+ .select((p) => (p.id, rowNumber(
+ partitionBy: [p.authorId], orderBy: [p.createdAt.desc(), p.id.desc()],
+ )).row).get();
+```
+
+Aggregates in `where`, ungrouped selected columns and invalid window placement
+are rejected before execution. Window functions preserve row count; group
+aggregates combine rows. A CTE exports its selected SQL expressions through
+`ref`, including when the Dart result is mapped to a DTO. An arbitrary DTO
+property or unselected expression is not an exported SQL column.
+
+Use `field.isInQuery(selectedQuery)`, `selectedQuery.existsExpression()` and
+`selectedQuery.scalar()` for nested SQL.
+A scalar subquery must have a provable single-row bound, such as an ungrouped
+aggregate or `take(1)`; a missing row produces null. Inner predicates may refer
+to the outer query's fields through an explicitly captured expression. Queries
+from different database/transaction objects cannot be combined.
+
+For SQL beyond these typed operations, use parameterized raw expressions or
+[checked named SQL](named-sql.md). Raw fragments are trusted SQL supplied by the
+application; do not interpolate user input into them.
+
+## UNION and UNION ALL
+
+Combine scalar expressions or SQL records with matching types:
+
+```dart
+final names = db.users.select((u) => u.email)
+ .union(db.posts.select((p) => p.title));
+final List result = await names.get();
+
+final rows = db.users.select((u) => (u.id, u.email).row)
+ .unionAll(db.posts.select((p) => (p.id, p.title).row))
+ .orderBy((row) => [
+ row.ref((u) => u.id).asc(),
+ row.ref((u) => u.email).asc(),
+ ]);
+
+final List<({int id, String label})> cards = await rows.take(20)
+ .map((row) => (id: row.$1, label: row.$2))
+ .get();
+```
+
+`union` removes duplicate **stored SQL rows**; `unionAll` keeps them. Neither
+promises operand order. Use a final `orderBy` when order matters. SQL equality,
+collations and NULL rules determine duplicates, independently of Dart `==`.
+These semantics follow [PostgreSQL set operations](https://www.postgresql.org/docs/current/queries-union.html)
+and [SQLite compound SELECT](https://www.sqlite.org/lang_select.html#compound_select_statements).
+
+Different Dart result types are rejected by the analyzer. Before execution, the
+ORM additionally requires matching positional columns, codec identities and
+nullability. Custom codecs must reuse the same instance. Different mappings to
+the same Dart type are not interchangeable. Nullable wrappers around a shared
+codec remain compatible; nullable and required columns must be explicitly
+aligned, for example with `alias.nullable(alias.fields.id)` in outer joins.
+
+Each operand must belong to the same `Database` object or transaction session.
+Combining a root query with a transaction query is rejected. Values remain bound
+parameters; PostgreSQL standalone `value(...)` expressions carry explicit SQL
+types so parameters in projections do not default to text.
+
+### Map after the set operation
+
+Arbitrary Dart mappers and loaded relationships are not SQL set columns:
+
+```dart
+// Rejected: these mappers have different behavior despite both returning String.
+final upper = db.users.select((u) => u.email.map((v) => v.toUpperCase()));
+final lower = db.posts.select((p) => p.title.map((v) => v.toLowerCase()));
+// upper.union(lower) throws QUERY.UNION_SELECTION.
+```
+
+Whole generated entities are Record/DTO mappings, so explicitly select their SQL
+fields with `.row` before combining them. Map the result afterward. For a SQL
+transformation, use an expression such as `u.email.upper()` before `union`.
+Putting a Dart-mapped query in a CTE does not bypass this rule. The ORM never runs
+a Dart mapper while planning SQL or guesses its behavior from its return type.
+
+## Scope and composition
+
+Operand filters, grouping, ordering and limits apply to that operand. Filters,
+ordering and limits after the set operation apply to the combined rows. Each
+operand is a derived table, which preserves its local clauses on both backends.
+The complete union executes as one SQL statement.
+
+`UnionFields.ref(...)` uses an expression exported by the **left** operand. An
+unselected column, incompatible codec or unsafe nullable reference fails before
+SQL execution. DTO property names are not exported SQL columns.
+
+```dart
+final recent = db.users.orderBy((u) => [u.id.desc()]).take(10)
+ .select((u) => u.email)
+ .unionAll(db.posts.orderBy((p) => [p.id.desc()]).take(10)
+ .select((p) => p.title));
+
+final filtered = recent.where((row) => row.ref((u) => u.email).like('a%'));
+final cte = filtered.asCte('recent_names');
+final selected = cte.query.select((c) => c.ref((row) => row.ref((u) => u.email)));
+await for (final name in selected.stream(batchSize: 64)) {
+ print(name);
+}
+```
+
+Nested sets preserve association: `a.unionAll(b).union(c)` differs from
+`a.unionAll(b.union(c))`. Each nesting adds an exported-expression scope, so
+references follow that nesting. CTEs can wrap sets, supply operands and be joined
+through typed aliases. Scalar sets also support `isInQuery` and, with `take(1)`,
+`scalar()`. `count`, `exists`, aggregation, `stream` and `watch` reuse normal query
+execution. Subscriptions collect table dependencies from both operands, including
+nested CTEs and SQL subqueries; existing raw-SQL notification rules still apply.
+
+Set results do not have declared primary/unique keys. Mutations and keyset cursor
+pagination are therefore rejected; offset/limit pagination and database cursor
+streaming are supported. `INTERSECT` and `EXCEPT` do not yet have typed methods.
+
+## Aggregate numeric results
+
+PostgreSQL returns `SUM(BIGINT)` and integer `AVG` as NUMERIC. Integer results are
+parsed exactly, with overflow or fractional values rejected rather than rounded
+through a double. On `int`/`double` expressions, `average()` returns an approximate
+`double?`. On `Decimal` expressions, `average(scale: ..., rounding: ...)` returns
+an exact `Decimal?` rounded once to the requested scale, including when the total
+would overflow. See [decimal arithmetic and averages](decimals.md).
diff --git a/docs/relations.md b/docs/relations.md
new file mode 100644
index 00000000..b9e96155
--- /dev/null
+++ b/docs/relations.md
@@ -0,0 +1,247 @@
+# Relationship queries
+
+Generated relation getters describe a query. They do not read data until a
+containing query executes. Select the exact related shape you need:
+
+```dart
+final cards = await db.posts.select((p) => (
+ p.title,
+ p.author.select((a) => (a.id, a.email)
+ .map((id, email) => (id: id, email: email))).required(),
+).map((title, author) => (title: title, author: author))).get();
+```
+
+## Navigation without foreign keys
+
+Use `relatesTo()` for a read-only navigation edge when the database does not
+enforce a foreign key. It uses the same checked key selectors and generated
+query API as `references()`:
+
+```dart
+typedef Account = ({int tenant, int id, String? label});
+typedef Entry = ({@Id() int id, int? tenant, int? owner});
+final accounts = entity();
+final entries = entity();
+final accountKey = accounts.primaryKey((a) => (a.tenant, a.id));
+final ownerAccount = entries.key((e) => (e.tenant, e.owner))
+ .relatesTo(accounts.key((a) => (a.tenant, a.id)), inverse: 'entries');
+```
+
+After generation, `e.ownerAccount.one()` returns an optional Account and
+`a.entries.many()` returns a list of Entry records. Normal projections, filters,
+correlated predicates, per-parent pagination, transactions, streams and watches
+apply. Generated getter documentation identifies the unconstrained edge.
+
+Matching rows may be missing, and lookup keys may be nonunique. `relatesTo()`
+does not infer a unique constraint or an index. Only an independently declared
+primary/unique key permits automatic to-one JOIN loading; otherwise `one()`
+uses a batch and checks cardinality. `required()` still reports missing matches.
+SQL equality does not match a composite key containing NULL. The key selectors
+must retain matching Dart and storage types, column order and arity.
+
+The edge itself exposes query operations. Create or change stored key values
+through the normal table write API, using a transaction when needed. There is no
+implicit connect, disconnect, cascade or existence validation, and `relatesTo()`
+has no `onDelete` option. Deleting a target can leave stored references dangling.
+`watch()` tracks the tables read by a selection, including joined or batched
+targets, without inventing foreign-key write effects.
+
+Adding, renaming or removing a query-only edge does not change the physical
+schema snapshot or emit migration DDL. Replacing an existing `references()` with
+`relatesTo()` does change the snapshot: removing that database constraint must
+go through a reviewed migration. Switching back can fail on dangling data; repair
+the data before retrying. Catalog import cannot discover unconstrained navigation
+rules, so declare them explicitly in the imported schema. This API covers
+same-database key equality, including self relations; it does not implement
+cross-database queries or arbitrary relationship predicate declarations.
+
+## Many-to-many with business fields
+
+An explicit association table gives each membership its own role and joining time.
+The [teams example](../example/teams/schema.dart) uses two foreign keys and a
+composite primary key, with no artificial membership ID:
+
+```dart
+enum MembershipRole { owner, member }
+typedef Membership = ({
+ int teamId,
+ int userId,
+ @Default.sql("'member'") MembershipRole role,
+ DateTime joinedAt,
+});
+final memberships = entity();
+final membershipKey = memberships.primaryKey((m) => (m.teamId, m.userId));
+final team = memberships.key((m) => m.teamId)
+ .references(teams.key((t) => t.id), inverse: 'memberships', onDelete: .cascade);
+final user = memberships.key((m) => m.userId)
+ .references(users.key((u) => u.id), inverse: 'memberships', onDelete: .cascade);
+```
+
+`teams` and `users` are separately declared entities. The resulting navigation is
+`user.memberships → membership.team`, or `team.memberships → membership.user`.
+Select the relationship's payload together with the opposite endpoint:
+
+```dart
+final cards = await db.users.select((u) => (
+ u.name,
+ u.memberships.orderBy((m) => [m.joinedAt.desc(), m.teamId.desc()]).take(2)
+ .select((m) => (m.team.select((t) => t.name).required(), m.role)
+ .map((team, role) => (team: team, role: role))).many(),
+).map((name, teams) => (name: name, teams: teams))).get();
+```
+
+This returns a typed list of user names and membership cards. Each membership's
+role belongs to that association; two users sharing a team can have different
+roles. An empty relationship returns `[]`. Use a deterministic tie breaker with
+per-parent pagination. Root pagination is independent of the membership limits.
+
+Create and update memberships through their ordinary generated table API:
+
+```dart
+await db.transaction((tx) async {
+ await tx.memberships.create(teamId: 10, userId: 1,
+ role: .set(MembershipRole.owner), joinedAt: DateTime.now());
+ await tx.memberships.byId(teamId: 20, userId: 1)
+ .patch(role: .set(MembershipRole.member));
+});
+await db.memberships.byId(teamId: 10, userId: 1).delete().execute();
+```
+
+The composite key rejects duplicate memberships. Both endpoints must already
+exist, or be created earlier in the same transaction. Unlinking deletes only the
+association. Deleting an endpoint follows the declared cascade, removing its
+memberships while retaining opposite endpoints. Composite-key `onConflictUpdate`
+can change a role while leaving the original joining time unchanged. There are
+no hidden object-graph saves or implicit writes through a navigation getter.
+
+The example declares one index beginning with `user_id` for reverse traversal;
+its primary key already begins with `team_id`. Additional ordering indexes depend
+on measured query patterns, not an index added automatically for every relation.
+
+Real SQLite/PostgreSQL checks establish these statement counts for the fixture,
+within the available parameter capacity:
+
+| Selection | SQL statements | Rows returned by each statement |
+| --- | --- | --- |
+| Four users, latest two memberships each, joined team names | 2 | 4, 5 |
+| Three teams, second member per team, joined user names | 2 | 3, 2 |
+| Four users, all memberships/teams, each team's complete roster | 3 | 4, 6, 6 |
+| Membership counts, every-member predicate and team-existence predicate | 1 | 4 |
+| Empty root result with a membership selection | 1 | 0 |
+
+Parameter chunking adds statements: with a deliberately limited five-parameter
+driver, a member-role filter and per-user limit execute one root plus two child
+statements. Roster lookups deduplicate shared team keys. These checks establish
+returned volume and statement counts, not throughput, physical database page reads
+or optimizer cost. Snapshot-consistency rules below still apply to multi-statement
+loads. `watch()` observes committed association and selected endpoint changes.
+
+Run the self-contained SQLite example:
+
+```sh
+dart run bin/orm.dart generate example/teams/schema.dart
+dart run example/teams/main.dart
+```
+
+It prints the selected records, SQL statement count and returned row counts. The
+same generated schema is exercised against PostgreSQL by `many_to_many_test.dart`.
+
+## Single relationships
+
+`one()` returns an optional related result. `required()` checks that a related
+row exists and reports `RELATION.MISSING` if it does not. Presence is checked
+independently of the selected values: a present row whose selected nullable
+column is NULL can still satisfy `required()`.
+
+The default `ToOneStrategy.automatic` uses a LEFT JOIN when the relationship
+keys cover a declared primary key, unique key or simple unique index on the
+target. That proves at most one match, so joining does not multiply root rows
+or change root pagination. Nested to-one projections use the same statement.
+
+You can select the strategy explicitly:
+
+```dart
+p.author.one(strategy: .join);
+p.author.required(strategy: .batch);
+```
+
+`.join` rejects keys that do not prove target uniqueness with
+`RELATION.JOIN_KEY`. Without that proof, `.automatic` uses batch loading and
+checks cardinality. More than one visible result produces
+`RELATION.CARDINALITY`. The uniqueness proof uses the schema declaration, so
+the actual database must enforce those declared constraints; use schema
+verification when adopting an existing database.
+
+Relation filters stay inside the JOIN condition and do not remove root rows.
+`one()` represents a filtered-out target as null; `required()` reports it during
+decoding. Selecting an all-null record still distinguishes a present record
+from an absent relationship using a separate marker. That marker avoids user
+column names, including SQLite's case-insensitive identifier collisions.
+
+A proven unique match has at most one row. `take(0)` and `skip(1)` therefore
+produce an absent joined relation. Ordering does not change that unique match.
+To deliberately select one row from a collection, use explicit ordering and
+`take(1).one(strategy: .batch)`.
+
+Each generated getter produces a fresh table occurrence. Use fresh getter calls
+when selecting differently filtered views of the same relationship:
+
+```dart
+final query = db.posts.select((p) => (
+ p.author.where((a) => a.score.gt(10)).one(),
+ p.author.where((a) => a.score.lte(10)).one(),
+).map((high, low) => (high: high, low: low)));
+```
+
+Reusing the identical edge with identical predicates deduplicates its JOIN.
+Reusing one edge with conflicting predicates produces `RELATION.ALIAS`; use
+fresh getters or select a batch strategy for the separate view.
+
+## Collections and composite keys
+
+`many()` uses batch loading and always returns a typed list. Empty relationships
+are empty lists, and an empty root result performs no child queries.
+
+```dart
+final users = await db.users.orderBy((u) => [u.id.asc()]).take(20)
+ .select((u) => (u.id, u.posts
+ .orderBy((p) => [p.createdAt.desc(), p.id.desc()])
+ .take(3).select((p) => p.title).many())
+ .map((id, titles) => (id: id, titles: titles)))
+ .get();
+```
+
+There is one root statement plus statements per relation and parameter chunk,
+not per parent. Duplicate parent keys share a lookup. A composite key with any
+NULL component does not match through SQL equality and is excluded from child
+lookup batches. Composite matches preserve tuple identity, so equal IDs in
+different tenants do not mix.
+
+Chunk capacity includes all bound parameters: key width, filters, projections,
+nested joins and per-parent window bounds. Large composite batches use row-value
+IN rather than deep OR trees. SQLite uses a VALUES subquery; PostgreSQL uses a
+row-constructor list so column types determine parameter types. See the
+[SQLite row-value rules](https://www.sqlite.org/rowvalue.html) and
+[PostgreSQL VALUES type rules](https://www.postgresql.org/docs/current/queries-values.html).
+
+Collection `take/skip` applies per parent using SQL window partitioning. It
+requires explicit ordering and window-function capability. The ORM does not
+fetch every child and discard excess rows in Dart. A collection's selected
+to-one relationships can join into that same child statement. Collections below
+a joined parent load in subsequent batches using the joined parent keys.
+
+`any/none/every/count` compile to correlated SQL and do not materialize related
+objects. `every` is true for an empty collection; a predicate returning SQL
+UNKNOWN counts as unsatisfied. Use `any` as well when an empty relationship
+should be excluded.
+
+`compile()` exposes the root SQL, including selected to-one JOINs. It does not
+pretend to contain the later collection statements. `inspect()` also describes
+conditional child SQL templates, output/key slots, joins and batch capacity;
+see [plans and observations](observability.md). `onQuery` reports every
+executed statement and fetched row count. Streaming uses these same strategies
+per root batch; see [execution](execution.md).
+
+Multiple statements can observe different snapshots under PostgreSQL Read
+Committed. Use an explicit Repeatable Read transaction when root and collection
+queries must share a snapshot. A JOIN-only selection is one statement.
diff --git a/docs/sqlite-web.md b/docs/sqlite-web.md
new file mode 100644
index 00000000..72d6cc4a
--- /dev/null
+++ b/docs/sqlite-web.md
@@ -0,0 +1,216 @@
+# SQLite in browsers and Flutter Web
+
+`package:orm/sqlite.dart` selects the native isolate or browser worker internally.
+Both execute through sqlite3's shared database/statement interfaces. Generated
+models, selections, relationships, transactions, migrations and subscriptions use
+one API.
+
+```dart
+import 'package:orm/sqlite.dart';
+import 'schema.orm.dart';
+
+final db = await sqlite(const SqliteOptions.persistent('app'));
+// Apply the application's reviewed Dart migration history before queries.
+final user = await db.users.create(email: 'seven@example.com');
+await db.close();
+```
+
+Use `SqliteOptions.memory()` for an isolated in-memory database. For the same
+persistent configuration on native platforms, provide `nativePath`:
+
+```dart
+final db = await sqlite(SqliteOptions.persistent(
+ 'app',
+ nativePath: databaseFilePath,
+));
+```
+
+The application owns its native directory choice; `nativePath` is unused on Web.
+`journal` and `busyTimeout` configure native connections. Browser persistence uses
+DELETE journaling, FULL synchronous mode and exclusive OPFS ownership; it does not
+apply native WAL/busy-wait settings.
+`SqliteOptions.file(path)` and `readOnly(path)` remain native file operations.
+Browser persistence uses the explicit name, never a guessed basename of a native
+path. Unsupported storage fails before opening a worker.
+
+## Flutter Web
+
+The ORM package declares its worker and SQLite WASM as Web-only Flutter assets.
+A Flutter consumer needs no worker source, manual downloads, asset declarations or
+URL configuration. `flutter run -d chrome`, `flutter build web` and
+`flutter build web --wasm` use the same database configuration. The default worker
+is compiled once by the package maintainer. Both application compilation modes
+use that JavaScript worker with the same SQLite WASM engine.
+
+See the runnable [Flutter example](../example/flutter/README.md). This packaging
+uses Flutter's platform asset filters, available since Flutter 3.41. The ORM stays
+a pure Dart package without an SDK Flutter dependency.
+
+Default resource resolution follows the document's HTML base, so a Flutter app
+built with `--base-href /app/` also works when opened directly at `/app/notes/42`.
+It does not resolve resource paths against the current route.
+
+## Plain Dart and custom deployment
+
+Copy the installed package's matching resources into your static files:
+
+```sh
+dart run orm web-assets # default output: web/orm/
+dart run orm web-assets public/orm # custom output directory
+```
+
+Plain Dart defaults to `orm/` under the HTML base. The command verifies the
+packaged hashes before copying and retains older deployment assets. It needs no
+worker compilation or WASM download. Serve JavaScript with a JavaScript MIME type
+and WASM with `application/wasm`.
+
+Advanced deployment can set `SqliteWebOptions` on `memory()` or `persistent()`:
+
+```dart
+final db = await sqlite(SqliteOptions.persistent(
+ 'app',
+ web: SqliteWebOptions(assetBase: Uri.parse('static/database/')),
+));
+```
+
+`assetBase` is the directory of the versioned files and must end with `/`.
+Individual `worker` and `wasm` URI overrides resolve against the HTML base.
+`worker` must be same-origin HTTP(S). WASM may use an explicitly configured CDN
+with appropriate CORS and CSP. Flutter's custom `assetBase` is not automatically
+read from private engine configuration: keep database resources same-origin or
+provide these explicit overrides. CDN/CSP deployment has not been certified.
+
+The client checks worker protocol/build identity before requesting database open.
+The browser verifies the SQLite module's subresource integrity before it is
+instantiated. A stale worker or wrong module fails explicitly. A custom compatible
+SQLite build must supply its own SHA-256 `wasmIntegrity` value. Stock resources are
+content-addressed; deploy them together with the app and retain resources needed
+by older open pages. Offline caching remains the application's deployment policy.
+
+For maintainers, `dart run tool/build_sqlite_web.dart` rebuilds the stock worker
+and pins the official sqlite3 3.6.0 module. `--check` verifies source and artifact
+fingerprints without rebuilding. The custom-worker entry remains
+`package:orm/sqlite_web_worker.dart`; its Dart `main()` calls
+`runSqliteWebWorker()`. Applications using the stock worker do not need it.
+
+## Storage and connection ownership
+
+An OPFS database lives under the origin-private `dart-orm/` directory. The
+underlying VFS persists `/database` and its rollback journal, and uses memory for
+temporary files. The driver requests DELETE journaling and FULL synchronous mode,
+and enables and verifies foreign keys before returning a connection. A memory
+database requests MEMORY journaling. Requested modes are checked against SQLite.
+
+OPFS requires a supporting browser and a secure context (localhost works for
+development). There is no implicit fallback to non-persistent memory or IndexedDB.
+The underlying sync access handles exclusively own the database. Opening another
+worker/tab for the same name fails while the first owns it. Await `db.close()` to
+release it before reopening. A single driver queues whole leases, so separate
+queries cannot enter someone else's transaction. This implementation does not
+coordinate a shared database service across tabs.
+
+`openTimeout` defaults to 15 seconds. Failed startup terminates the failed worker;
+normal close first closes statements, the database and OPFS handles, then terminates
+the worker. Schema migrations run through the same owned connection. The browser
+acceptance test reloads a page with a transaction still open, verifies recovery of
+committed data and rollback of that transaction, then applies a versioned upgrade.
+
+OPFS data remains subject to the browser's quota, eviction and user-clearing rules.
+The sqlite3 3.6.0 WASM API is explicitly marked experimental, including the future
+stability of VFS storage formats. This adapter's Chromium acceptance is not a
+cross-browser production certification. The implementation follows the package's
+[dedicated-worker OPFS API](https://pub.dev/documentation/sqlite3/latest/wasm/SimpleOpfsFileSystem-class.html).
+
+## Numeric and temporal boundaries
+
+JavaScript represents int and double with the same underlying number type and
+cannot distinguish every 64-bit integer. See [Dart number semantics](https://dart.dev/resources/language/number-representation).
+The worker protocol rejects untagged integer parameters outside
+`-9007199254740991..9007199254740991`. Use BigInt for wider integers. SQLite int64
+results beyond the safe range cross the worker boundary as exact BigInt values,
+not rounded doubles. Generated int fields must remain in the safe range; decoding
+an incompatible value fails. This bridge applies the same rule to JS and WASM
+clients so their storage contract is consistent.
+
+`Codecs.real` preserves floating-point intent automatically on web builds, including
+integral doubles such as `1e20`. For raw SQL or custom encoders, `SqlReal(1e20)` is
+an explicit floating parameter; SQLite binds it with the native double API.
+SqlReal is also accepted by native SQLite/PostgreSQL drivers. Raw PostgreSQL SQL
+still needs suitable SQL casts/context to establish parameter/result types.
+Finite floating values retain their value through versioned keyset cursor tokens,
+including a unique tie breaker when several rows have the same floating value.
+
+Blobs use structured-clone typed arrays. BigInt uses tagged decimal text. Decimal
+parameters and SQLite arithmetic use the same exact implementation and registered
+functions as native SQLite. LocalDate, LocalTime and LocalDateTime remain explicit
+calendar values. UTC DateTime encoding uses date/time components, and browser
+decoding avoids a lossy total-microseconds JS number. Acceptance includes BC dates
+and microseconds near DateTime's upper bound. Calling SDK arithmetic that loses
+precision before passing a value to the ORM cannot be repaired by the driver.
+
+## Capabilities and observable cost
+
+Queries run in the worker, leaving the browser event loop responsive. Streaming
+uses a real prepared cursor and fetches bounded batches through worker messages.
+Closing or cancelling a stream releases its statement and lease. Ordinary get()
+still materializes its complete result; use streaming/pagination for large reads.
+Messages incur structured-clone and decoding costs; no zero-copy or throughput
+claim is made.
+
+Statement interruption is unavailable with this synchronous WASM API, so
+`capabilities.cancellation` is false. Statement deadlines/cancellation and
+transaction deadline/retry options that require interruption fail before execution.
+This does not prevent ordinary transactions, savepoints, acquisition limits or
+early cursor release. Do not treat worker termination as proof of a SQL rollback
+or as a replacement for confirmed commit outcomes.
+
+`watch()` merges known writes after commit and emits fresh snapshots. It does not
+observe another origin, tab or independent database connection. Named SQL queries
+retain their explicit `reads:` requirement. Same-origin persistence, browser
+storage permission and database ownership are separate from reactive invalidation.
+
+## Reproducible acceptance
+
+```sh
+dart run tool/test_browser.dart
+dart run tool/test_browser.dart --wasm
+dart run tool/test_flutter_web.dart /absolute/path/to/flutter
+```
+
+The runner verifies packaged resource fingerprints, copies the matching assets,
+checks generated fixture freshness, compiles the client, starts a local asset
+server, and launches Chrome
+with a disposable profile. Set `CHROME_EXECUTABLE` to override its path. It writes
+`report.js.json` or `report.wasm.json` under `.dart_tool/browser/` and fails if the
+browser reports any failed check. Reports contain the actual browser, Dart SDK,
+compilation mode and engine checksum. The captured results are in
+`research/validation/browser.json`.
+
+The subsequent [API audit capture](../research/validation/api-audit.md) passes
+20 checks in each compilation mode, adding mixed-session query rejection,
+independent optional-join guards and rejected-write state checks. Its logs are
+separate from the original browser capture.
+
+Run these separately from the native full suite: concurrent Dart CLI invocations
+can race while rewriting/codesigning the shared macOS native-asset cache. The
+acceptance checks cover memory migration/catalog checks, FK and CHECK enforcement,
+atomic constraint migration rollback, client defaults with explicit null and
+prepared batch values, stored/virtual computed fields and expression migrations,
+many-to-many payloads and pagination with measured query/row counts, generated
+relations, transactions/savepoints/lifetime, cursors, subscriptions, numeric and
+calendar codecs, unsupported interruption, event-loop responsiveness, startup
+failures, exclusive OPFS ownership, reopening, page reload recovery and upgrades.
+The plain Dart runs do not establish Flutter embedding. Neither runner measures
+throughput or establishes Safari, Firefox, IndexedDB or multi-tab service support.
+
+The unified-entry acceptance adds actual Flutter release builds in JS and WASM,
+with and without cross-origin isolation headers. The app consumes the package's
+unchanged asset declarations and default URI resolution from a nested route.
+It also checks stale worker rejection and WASM integrity failure. See
+[the refactor validation](../research/validation/sqlite-refactor.md).
+
+Hot reload retains application state. Flutter Web hot restart, which can abandon
+live JS resources without closing them, is not certified by these release tests;
+close the database or refresh the page when restarting a live OPFS session.
+Multi-tab sharing, automatic storage fallback and cross-tab watch propagation
+remain outside this driver. A second owner fails rather than bypassing OPFS locks.
diff --git a/docs/types.md b/docs/types.md
new file mode 100644
index 00000000..e07966ff
--- /dev/null
+++ b/docs/types.md
@@ -0,0 +1,462 @@
+# Domain types and storage
+
+Record fields keep their Dart types throughout generated creation, patches,
+predicates, projections, relationships and cursor values. A codec describes the
+storage boundary: `encode` produces a driver value, and `decode` validates and
+constructs the application value.
+
+## Custom IDs and values
+
+Declare a public constant codec beside its type:
+
+```dart
+import 'package:orm/schema.dart';
+
+extension type const UserId(int value) {
+ static const codec = Codec.integer(_decode, _encode);
+ static UserId _decode(Object? value) => UserId(value as int);
+ static int _encode(UserId value) => value.value;
+}
+
+typedef User = ({
+ @Id.generated() @UseCodec(UserId.codec) UserId id,
+ String name,
+});
+final users = entity();
+```
+
+After generation, `db.users.byId(UserId(1))` accepts the domain ID;
+`db.users.byId(1)` is a static error. Use the same domain ID codec on foreign-key
+fields. Required integer primary keys can retain database-generated identities.
+
+`Codec.text(decode, encode)` and `Codec.integer(decode, encode)` constrain
+the encoder's return type. The general `Codec(storage, decode, encode)` accepts
+the storage tags in the table below. It is the application's responsibility to
+validate the representation and keep encoding deterministic.
+
+`@UseCodec` accepts a **public const variable or public static const field**.
+The generator checks the reference's resolved Dart type and reads the constant
+storage tag. It never calls application encoders, decoders or model constructors.
+Private references and inline codec constructors are rejected. A nullable field
+can use a non-nullable codec; the generated client adds `.nullable()` so SQL
+`NULL` bypasses the domain decoder. A nullable codec cannot back a required field.
+
+Imported types, extension types, public record aliases and nested generic types
+retain qualified names in generated code. Two different libraries may both
+declare `Email`. Output can be generated into a different directory.
+
+See the complete [domain fixture](../test/support/codecs/schema.dart) and its
+[types](../test/support/codecs/types.dart). `Codec.map` remains available when
+constructing table definitions directly at runtime.
+
+## Enums
+
+```dart
+enum Membership {
+ @EnumValue('pending-payment') pending,
+ active,
+ @EnumValue('closed') cancelled,
+}
+
+typedef Account = ({
+ @Id() int id,
+ Membership membership,
+ Membership? previousMembership,
+});
+```
+
+Enums use text labels. Without `@EnumValue`, the label is the constant's Dart
+name. Explicit labels allow a Dart rename without changing stored data. Ordinals
+are never stored. Duplicate labels fail generation; an unknown stored label fails
+decoding with `CODEC.ENUM`. The runtime equivalent is `Codecs.enumeration` with
+an explicit enum-to-label map.
+
+This is portable text storage, with no native enum or automatically generated
+`CHECK` constraint. A database writer can therefore insert an unknown label;
+the decoder detects it when read. Adding or renaming stored labels requires a
+reviewed data migration and compatibility with any still-running application
+versions.
+
+## Structured JSON
+
+Use a codec for a structured value, including a record:
+
+```dart
+import 'dart:convert';
+import 'package:orm/schema.dart';
+
+typedef Location = ({String city, int zone});
+const locationCodec = Codec('json', decodeLocation, encodeLocation);
+
+Location decodeLocation(Object? raw) {
+ final json = Codecs.json.decode(raw) as Map;
+ return (city: json['city'] as String, zone: json['zone'] as int);
+}
+String encodeLocation(Location value) =>
+ jsonEncode({'city': value.city, 'zone': value.zone});
+
+typedef Place = ({
+ @Id() int id,
+ @UseCodec(locationCodec) Location? location,
+});
+```
+
+Use `Codecs.json.decode(raw)` inside a custom JSON decoder. SQLite supplies JSON
+text; PostgreSQL supplies parsed data wrapped in `SqlJson`. This bridge handles
+JSON strings without decoding them twice. A JSON document containing `null` is
+passed to the domain decoder; it does not bypass validation as SQL `NULL` does.
+
+For an arbitrary document with explicit presence:
+
+```dart
+typedef Event = ({
+ @Id() int id,
+ @UseCodec(Codecs.jsonDocument) SqlJson? payload,
+});
+
+// In generated create/patch arguments:
+// null -> SQL NULL
+// SqlJson(null) -> JSON null
+// SqlJson('text') -> JSON string
+// SqlJson({'a': 1}) -> JSON object
+```
+
+Read the document through `.value`. `field.isNull()` tests SQL nullness. For
+ordinary JSON values, `Codecs.json` returns the parsed Dart value, including
+`null`; that value alone cannot distinguish JSON null from SQL null. `jsonEncode`
+determines which payloads are serializable. Use a domain codec to validate their
+shape and reconstruct application types.
+
+Raw PostgreSQL results also use `SqlJson` for non-SQL-null `json`/`jsonb` columns.
+Decode these with `Codecs.json` when consuming portable raw results. JSON values
+as relational keys have not been validated and are outside the current verified
+key support; use scalar IDs for relationships.
+
+## Physical storage and migrations
+
+| Storage tag | Built-in Dart value | SQLite | PostgreSQL |
+| --- | --- | --- | --- |
+| `integer` | `int` | `INTEGER` | `BIGINT` |
+| `bigint` | `BigInt` | `TEXT` | `NUMERIC` |
+| `decimal` | `Decimal` | collated `TEXT` | `NUMERIC` |
+| `real` | `double` | `REAL` | `DOUBLE PRECISION` |
+| `text` | `String`, enums | `TEXT` | `TEXT` |
+| `boolean` | `bool` | `INTEGER` | `BOOLEAN` |
+| `instant` | UTC `DateTime` | collated UTC text | `TIMESTAMPTZ` |
+| `date` | `LocalDate` | collated `TEXT` | `DATE` |
+| `time` | `LocalTime` | collated `TEXT` | `TIME WITHOUT TIME ZONE` |
+| `local_datetime` | `LocalDateTime` | collated `TEXT` | `TIMESTAMP WITHOUT TIME ZONE` |
+| `blob` | `Uint8List` | `BLOB` | `BYTEA` |
+| `json` | JSON value or custom codec | JSON text | `JSONB` |
+
+Snapshots record physical storage, nullability, defaults and constraints. They
+do not embed application functions. Changing a codec's validation or enum labels
+without changing storage does not create a DDL diff; write an explicit data
+migration when existing stored values need conversion. Changing storage uses the
+normal reviewed migration diff/conversion workflow.
+
+Storage semantics still belong to each database. In particular, SQLite `bigint`
+text retains exact digits but does not provide numeric text ordering/arithmetic.
+Native enum types remain a backend extension. Browser numeric limits and tested
+transport are described in [SQLite web](sqlite-web.md). Use `Decimal` for exact
+decimal data.
+
+## UTC instants
+
+Declare an instant as `DateTime`. Generated writes accept UTC or local DateTime
+objects and preserve their actual instant; reads return UTC. `Codecs.dateTime`
+is a constant codec with the `instant` storage tag. Its text representation has
+six fractional digits, a `+00` offset and an explicit BC suffix when applicable.
+
+SQLite uses `TEXT COLLATE orm_instant_v1`; comparisons operate on instants rather
+than lexicographic text. This preserves microsecond order, equivalent offsets,
+BC and extended years, uniqueness, relationship keys, window aggregates and
+stable cursors. The same collation backs column indexes. PostgreSQL uses native
+TIMESTAMPTZ and binary decoding independent of session DateStyle and timezone.
+
+Timestamp text may have a numeric UTC offset or `Z`. Zone-less database text is
+defined as UTC, including SQLite's CURRENT_TIMESTAMP default; it is never parsed
+using the process timezone. Invalid dates, leap seconds, excessive fractional
+precision and invalid offsets fail decoding. IANA timezone names are not parsed
+by this codec. Applications must explicitly resolve civil times and timezone rules
+before constructing the DateTime they store. SQLite's default itself has second
+resolution; precise application values retain their microseconds.
+
+Supported instants run from 4714-11-24 00:00:00 BC through 275760-09-13 00:00:00
+UTC. The upper bound follows [Dart DateTime's range](https://api.dart.dev/dart-core/DateTime-class.html),
+and the lower bound follows PostgreSQL. The PostgreSQL decoder checks bounds
+before adding epoch offsets, so larger native values cannot wrap through int64.
+Raw finite values beyond DateTime's range and infinities remain text; typed
+instant decoding rejects them. These range and precision guarantees are verified
+on native Dart, not JavaScript or browser storage.
+
+Native drivers advertise `Capabilities.temporal`, covering the local types below
+and UTC instants. Borrowed PostgreSQL pools must use `postgresTypeRegistry()` and
+`PostgresDriver.borrow(pool, temporal: true)`. Without that capability, typed
+temporal queries fail before execution. This replaces the earlier preview's
+`localTemporal` flag; no compatibility alias is provided.
+
+### Upgrading historical timestamp storage
+
+Previously generated `timestamp` snapshots retain their original storage meaning:
+SQLite TEXT with BINARY ordering, or PostgreSQL TIMESTAMPTZ. Their serialized
+snapshots, SQL and migration checksums remain unchanged. New generation emits
+`instant`, which produces a visible, reviewed type change. Do not recreate an
+applied migration from the current application schema.
+
+```dart
+final upgrade = Migration.diff(
+ '0002_instants',
+ dialect: .sqlite,
+ from: previous.snapshot!,
+ to: SchemaSnapshot(currentSchema),
+ previous: previous.checksum,
+ using: {
+ 'events': {'created_at': 'orm_instant_v1(created_at)'},
+ },
+);
+```
+
+For a PostgreSQL history use `dialect: .postgres` and the reviewed conversion
+`using: {'events': {'created_at': 'created_at'}}`. Only that history's expression is needed.
+
+The SQLite converter parses and canonicalizes each value with UTC semantics;
+the rebuild installs the new collation. Invalid timestamps or newly equivalent
+unique keys abort the migration and roll back its changes. Audit zone-less legacy
+text before conversion: if an external writer stored local civil time there,
+provide a reviewed conversion using its actual timezone. PostgreSQL already stores
+instants, so the shown conversion preserves values; existing infinities or values
+beyond DateTime's range still require separate data review. Old cursor tokens
+carry the old storage tag and cannot be reused under the new ordering contract.
+
+The [captured legacy migration](../test/support/instants/m0001_legacy.dart) is tested
+against its checksum from commit `00853b4`, including upgrade and rollback on real
+databases. Plain unmanaged SQLite TEXT still imports as String; the managed
+instant collation lets the importer infer DateTime without sampling data.
+
+## Local calendar values
+
+```dart
+typedef Appointment = ({
+ @Id.generated() int id,
+ LocalDate day,
+ @Default.sql("'12:30'") LocalTime time,
+ LocalDateTime? starts,
+});
+final appointments = entity();
+
+// After generation:
+await db.appointments.create(
+ day: LocalDate(2024, 2, 29),
+ time: Change.set(LocalTime(12, 30)),
+ starts: LocalDateTime.parse('2024-02-29 12:30:00.000001'),
+);
+```
+
+These values have no timezone or implied UTC instant. `DateTime`, strings and
+other local temporal types cannot be substituted in generated predicates or
+writes. `LocalDateTime` combines a `LocalDate` and `LocalTime`. Its `add(Duration)`
+uses calendar days of exactly 24 hours; it does not perform timezone or daylight
+saving conversion. `LocalDate.addDays` and `daysUntil` operate on calendar dates.
+
+| Value | Supported finite range |
+| --- | --- |
+| LocalDate | 4714-11-24 BC through 5874897-12-31 |
+| LocalTime | 00:00:00 through 24:00:00, at microsecond resolution |
+| LocalDateTime | 4714-11-24 00:00:00 BC through 294276-12-31 23:59:59.999999 |
+
+Constructors use astronomical year numbers: year 0 is 1 BC, and year -1 is 2 BC.
+Text parsing accepts those year numbers or PostgreSQL's trailing ` BC` notation.
+Serialization uses era notation; times always include six fractional digits.
+Invalid calendar dates, offsets, leap seconds and excess fractional precision are
+rejected. `24:00` is a distinct time-of-day endpoint; combining it with a date
+normalizes to the next date at `00:00`. Addition beyond the finite range fails.
+The exact endpoints come from PostgreSQL's [timestamp constants](https://github.com/postgres/postgres/blob/REL_18_STABLE/src/include/datatype/timestamp.h).
+The Gregorian ordinal conversion uses March-based 400-year cycles, as described
+in [civil date algorithms](https://howardhinnant.github.io/date_algorithms.html).
+
+`Codecs.date`, `Codecs.time` and `Codecs.localDateTime` accept their corresponding
+value type or valid text, never a `DateTime`. An owned PostgreSQL pool uses native
+binary decoders, so it does not truncate these ranges to Dart's `DateTime` range.
+Binary reads remain independent of session DateStyle and timezone. Raw date and
+timestamp infinity values remain strings; typed calendar decoding rejects them.
+For a borrowed PostgreSQL pool, configure it before opening connections:
+
+```dart
+import 'package:orm/postgres.dart';
+import 'package:postgres/postgres.dart' as pg;
+
+final pool = pg.Pool.withEndpoints(endpoints,
+ settings: pg.PoolSettings(typeRegistry: postgresTypeRegistry()),
+);
+final db = Database(PostgresDriver.borrow(pool, temporal: true));
+```
+
+The default borrowed-pool capability is false; temporal queries fail before
+execution until explicitly enabled. The registry's text fallback accepts ISO
+DateStyle only. The capability covers these three scalar types and UTC instants; arrays, ranges,
+intervals, time with timezone and timezone conversions are still outside it.
+
+SQLite stores text with `orm_date_v1`, `orm_time_v1` or `orm_local_datetime_v1`
+collations. They compare parsed calendar values, including equivalent text forms,
+BC dates and extended years. Predicates, min/max, grouping, unique keys, foreign
+keys, relations and keyset cursors preserve that ordering, and column indexes
+use the same collation. External SQLite connections need matching registrations
+to use those tables and indexes. No calendar-validation CHECK is emitted:
+invalid external text sorts after valid values and fails typed decoding.
+
+Snapshots preserve distinct storage tags. Catalog import recognizes native
+PostgreSQL scalar types and the three managed SQLite collations. Plain SQLite
+TEXT does not imply a calendar type. Changing text to a calendar type requires a
+reviewed migration; newly equivalent unique keys can make conversion fail and
+roll back. Historical backfills persist canonical text keys for resumable paging.
+
+SQL calendar arithmetic and timezone-rule conversion have no typed API in this
+version; they are separate [extension boundaries](capabilities.md#values-and-physical-storage).
+Use local types when the domain value actually has no timezone; use DateTime for
+resolved instants.
+
+## Temporal precision
+
+```dart
+typedef Event = ({
+ @Id.generated() int id,
+ @TemporalPrecision(3) LocalTime clock,
+ @TemporalPrecision(3) LocalDateTime appointment,
+ @TemporalPrecision(0) DateTime occurredAt,
+});
+final events = entity();
+```
+
+`@TemporalPrecision` accepts 0 through 6 fractional second digits on `LocalTime`,
+`LocalDateTime` and `DateTime`, including nullable fields and domain codecs with
+the corresponding storage tag. Manual `Column` declarations use
+`temporalPrecision: 3`. Date-only and unrelated storage types are rejected.
+Omitting precision retains microseconds. Explicit six and the default have the
+same canonical snapshot and DDL, preserving existing migration checksums.
+
+| Dart value | PostgreSQL column | SQLite column |
+| --- | --- | --- |
+| `LocalTime` | `TIME(p) WITHOUT TIME ZONE` | collated TEXT with precision CHECK |
+| `LocalDateTime` | `TIMESTAMP(p) WITHOUT TIME ZONE` | collated TEXT with precision CHECK |
+| `DateTime` | `TIMESTAMPTZ(p)` | UTC text with precision CHECK |
+
+The precision range follows PostgreSQL's [date/time type contract](https://www.postgresql.org/docs/18/datatype-datetime.html).
+ORM inserts, updates, batches and upserts coerce assigned expressions in SQL.
+SQLite defaults, computed expressions and migration copies use the same registered
+function. Raw PostgreSQL writes undergo native column coercion; raw SQLite writes
+with excess nonzero digits fail the CHECK instead of silently changing the input.
+External SQLite connections need these ORM functions and collations registered.
+Default/six-digit columns retain their previous validation behavior.
+
+Rounding matches PostgreSQL's [timestamp implementation](https://github.com/postgres/postgres/blob/REL_18_STABLE/src/backend/utils/adt/timestamp.c)
+and [time implementation](https://github.com/postgres/postgres/blob/REL_18_STABLE/src/backend/utils/adt/date.c):
+nearest representable value, with exact halves away from midnight for `LocalTime`
+and away from 2000-01-01 for timestamps. Instant rounding uses the UTC timeline.
+For example, at three digits, `2000-01-01 00:00:00.0005` becomes `.001`, while
+`1999-12-31 23:59:59.9995` becomes `.999`. A time can reach `24:00`; a timestamp
+can move into the next day. Values outside the supported finite range are rejected.
+
+Value methods and SQL expressions expose the same explicit operation:
+
+```dart
+final rounded = LocalTime.parse('12:00:00.1235').withPrecision(3);
+final selected = await db.events
+ .select((e) => e.appointment.withPrecision(0))
+ .get();
+```
+
+`withPrecision` also applies to local timestamps and resolved DateTime instants;
+the DateTime operation returns UTC.
+SQL results preserve nullable types. The operation composes with projections,
+CTEs, grouping and streams. Column precision does not change the value codec or
+implicitly round predicate parameters. Use the returned stored key, or explicitly
+round a lookup value, when precision affects a primary/foreign key.
+
+Catalog inspection, CLI inspection and import retain precision. Recognized SQLite
+precision checks and coercion wrappers are interpreted as column metadata; other
+checks remain visible. Import drafts defaults and computed SQL without adding a
+second SQLite wrapper. Changing precision is a type change and requires reviewed
+conversion expressions for the selected database. Rounding can merge unique keys; such a
+failure rolls back the data, schema and migration history together. Renames retain
+the precision metadata.
+
+`temporal_precision_test` covers native SQLite/PostgreSQL values, generated writes,
+all seven precisions around the PostgreSQL epoch, defaults/computed values,
+relations, batch/upsert rollback, import, catalog drift and reviewed migration
+rollback. The browser precision scenario additionally checks BC dates, extended
+timestamps and the maximum DateTime boundary through the worker. These checks do
+not establish native Flutter behavior or add timezone conversion support.
+
+## Signed integer column widths
+
+```dart
+typedef Counter = ({
+ @Id.generated() @IntegerBits(32) int id,
+ @IntegerBits(16) int small,
+ @IntegerBits(32) int? optional,
+ int total,
+});
+final counters = entity();
+```
+
+`@IntegerBits` accepts 16, 32 or 64 on fields with integer storage, including
+integer-backed domain codecs. Omitting it means 64. For manual tables, pass
+`integerBits: 16` to `Column`. Explicit 64 and the default have the same serialized
+schema and produce no migration difference.
+
+Width belongs to the column metadata. It does not replace the `int` value codec
+or constrain an aggregate to its source column's range. PostgreSQL SUM over
+SMALLINT/INTEGER produces BIGINT; the generated API decodes wider results normally.
+Other arithmetic and overflow follow the database's native rules. See PostgreSQL's
+[numeric types](https://www.postgresql.org/docs/current/datatype-numeric.html) and
+[aggregate return types](https://www.postgresql.org/docs/current/functions-aggregate.html).
+
+| Width | PostgreSQL | SQLite column constraint |
+|---|---|---|
+| 16 | SMALLINT | integer storage value between -32768 and 32767 |
+| 32 | INTEGER | integer storage value between -2147483648 and 2147483647 |
+| 64/default | BIGINT | normal INTEGER storage |
+
+SQLite still uses its native variable-sized integer representation, not a forced
+two- or four-byte layout. For 16/32, DDL adds a CHECK which permits NULL when the
+column is nullable and otherwise requires an integer within the signed range.
+Default 64 retains ordinary SQLite INTEGER affinity. ORM writes use Dart `int`;
+SQLite's affinity and raw SQL rules are documented in
+[its datatype reference](https://www.sqlite.org/datatype3.html).
+
+Catalog inspection recognizes the emitted SQLite range checks while ignoring
+quoted defaults and comments. It does not claim to prove equivalence of arbitrary
+handwritten CHECK expressions; those remain unmanaged. Column checks and full
+schema verification both compare the inferred width. Catalog import emits
+`@IntegerBits` for PostgreSQL SMALLINT/INTEGER and recognized SQLite range checks.
+
+Width changes are type changes in migration history. Supply reviewed conversion
+expressions for the selected database, even for widening. PostgreSQL alters the native
+type; SQLite rebuilds the table with the new constraint. Data outside a narrowed
+range fails and rolls back the migration/history together. Physical column renames
+retain the width. Changing an identity column's width preserves generation and, on PostgreSQL,
+the associated sequence type. Backfills use their saved width metadata when
+verifying the historical schema.
+
+Native JIT and AOT checks include integer values beyond JavaScript's exact-number
+range. Browser int values use the safe-number range; verified wider transport
+uses BigInt. See [SQLite web](sqlite-web.md) for the boundaries and browser checks.
+
+## Verification
+
+The generated domain fixture runs against native SQLite and PostgreSQL. Checks
+cover writes, parameters, patches, invalid stored values, JSON scalar/null
+semantics, joined/batched relations, batch/upsert, cursor transport, streaming and
+catalog verification. Generator tests reject mismatched codecs and preserve
+nullable aliases. Negative compilation tests use the actual generated APIs.
+`test/support/codecs/native.dart` also compiles and runs as a native macOS AOT
+program. These checks do not establish browser support.
+
+## Exact decimals
+
+Use `Decimal` for finite base-ten values, including money. Generated fields use
+`Codecs.decimal` without an annotation. See [exact decimals](decimals.md) for
+construction, arithmetic, numeric keys, SQLite storage requirements and current
+limits. `BigInt` storage does not provide these fractional or SQLite numeric
+ordering semantics.
diff --git a/docs/watch.md b/docs/watch.md
new file mode 100644
index 00000000..1c379de5
--- /dev/null
+++ b/docs/watch.md
@@ -0,0 +1,151 @@
+# Query subscriptions
+
+`watch()` emits an initial query result, then re-runs the query after relevant
+committed writes:
+
+```dart
+final subscription = db.users
+ .orderBy((u) => [u.id.asc()])
+ .select((u) => u.email)
+ .watch()
+ .listen(
+ (emails) => print(emails), // List
+ onError: (Object error) => print(error),
+ );
+
+await db.users.create(email: 'seven@example.com');
+await subscription.cancel();
+```
+
+Each stream has one subscriber and starts work only when listened to. Create a
+separate `watch()` for another subscriber. Each subscription executes its own
+query; there is no global result cache, object identity map or polling timer.
+Each refresh uses normal `query.get()` semantics, including relationship batches.
+Bound snapshot size with filters and `take`; use `query.stream()` for incremental
+row consumption through a database cursor.
+
+## Commit behavior
+
+Typed insert, update, delete, upsert and batch operations record affected tables.
+Zero-row writes and `ON CONFLICT DO NOTHING` with no inserted rows do not refresh
+queries. Raw operations can explicitly declare effects as described below.
+
+```dart
+await db.transaction((tx) async {
+ await tx.users.create(email: 'a@example.com');
+ await tx.users.create(email: 'b@example.com');
+}); // One combined invalidation after COMMIT succeeds.
+```
+
+A rolled-back transaction produces no invalidation. Released savepoints merge
+their changes into the enclosing transaction; rolled-back savepoints discard
+their changes. A batch's chunks follow the same transaction boundary. SQL and
+constraint failures do not publish successful-write notifications.
+
+If COMMIT's acknowledgement is lost, its outcome may be unknown. The transaction
+still throws `TRANSACTION.COMMIT`, and subscriptions conservatively re-read its
+affected tables. A refreshed result is not evidence that retrying the mutation is
+safe. The PostgreSQL test executes a real commit before injecting this fault.
+
+Subscriptions observe invalidation and current data, not an audit log of every
+intermediate state. Several commits may coalesce while a read is running or a
+subscription is paused. Results are not compared for equality automatically;
+an affected-table write may emit an unchanged projection. Consumers can apply
+`distinct` with their own equality function if required.
+
+## Which queries refresh
+
+The compiler tracks physical sources used by root queries, explicit and automatic
+JOINs, subqueries, CTEs, relation predicates and nested batch-loaded relations.
+An unrelated table write does not execute another read.
+
+Generated clients register their schema metadata. Declared foreign-key delete
+effects then propagate through `CASCADE` chains; `SET NULL` invalidates the child
+without treating that child as deleted. Ordinary updates do not trigger a
+delete cascade. For hand-authored tables, register the full relevant schema:
+
+```dart
+db.registerSchema([usersSchema, postsSchema]);
+```
+
+Read dependencies are captured before the first read starts. An invalidation
+arriving during a read marks that result stale; the subscription re-reads before
+emitting it. Only one read runs per subscription at a time. Normal query and
+relation loading semantics still apply; subscriptions do not add a stronger
+cross-statement transaction isolation guarantee.
+
+## Raw SQL, triggers and external writers
+
+Table names hidden inside raw SQL cannot be discovered from a typed expression.
+Add those dependencies explicitly:
+
+```dart
+final postCount = sql(
+ ['(SELECT COUNT(*) FROM posts)'], [], Codecs.integer,
+);
+final counts = db.users.select((_) => postCount).watch(reads: [postsSchema]);
+```
+
+Raw commands can declare tables they affect:
+
+```dart
+await db.execute(
+ SqlCommand('DELETE FROM posts'),
+ changedTables: [postsSchema],
+);
+```
+
+`changedTables` requests an invalidation after a successful command even when its
+reported row count is zero. It follows the current transaction/savepoint boundary
+and conservatively includes declared delete effects. It is explicit metadata;
+the ORM does not parse arbitrary SQL to infer writes.
+
+For triggers, procedures or already-committed external work, notify explicitly:
+
+```dart
+db.invalidate([postsSchema]);
+```
+
+Inside a transaction, `tx.invalidate(...)` waits for that transaction's commit.
+Supply all tables affected by unmodeled triggers or procedures. Independent
+SQLite connections, PostgreSQL pools and other processes do not automatically
+notify each other. Integrate an external notification, polling or CDC mechanism
+and call `invalidate` after observing the external commit. Separate database
+views using the **same driver instance** share notifications.
+
+## Pause, cancellation and errors
+
+- Pausing a subscription prevents additional reads. Writes set one dirty flag;
+ resuming performs a fresh read. A read already in progress may finish, but its
+ result is discarded if the subscriber is paused, avoiding a growing result queue.
+- Cancelling the subscription stops future reads and interrupts active SQL when
+ the driver supports cancellation. Await cancellation to wait for the active read
+ and its connection cleanup. A driver without cancellation must finish its read.
+- `ExecutionOptions.timeout` limits each SQL statement, including relation
+ batches. It is not a lifetime limit for the subscription.
+- An optional cancellation token cancels the subscription with
+ `OPERATION.CANCELLED` and closes it. Explicit subscription cancellation is silent.
+- Query/decoding failures emit errors. A later invalidation can retry; errors do
+ not create a polling or automatic retry loop. Invalid subscription/query
+ definitions detected before the first read are terminal.
+- `Database.close()` stops its driver's subscriptions and waits for active reads.
+ A paused listener cannot prevent database shutdown; it observes stream completion
+ when resumed or cancelled.
+
+Watch a root database query. Transaction and leased-session queries reject
+subscription with `WATCH.SESSION`: those views expire when their callback returns.
+Also avoid awaiting an outside subscription from code holding the only available
+connection; its next read must wait for that lease to be released.
+
+## Verification
+
+The suite covers both native SQLite and PostgreSQL, including real independent
+SQLite workers and PostgreSQL connections, joined/CTE/relation dependencies,
+savepoint rollback, multi-level cascades, pause, cancellation and database close.
+Controlled completed-read and commit-acknowledgement faults exercise race handling
+against real database state. Negative compilation checks verify subscription
+result types. The native execution example also verifies subscriptions in macOS
+AOT. Real Chrome JavaScript and Dart WASM runs verify worker subscriptions;
+the [native Flutter application](flutter.md) also verifies initial delivery,
+committed relation writes, rollback without notification and typed patch refresh
+inside an Android AOT release application.
diff --git a/example/flutter/.gitignore b/example/flutter/.gitignore
new file mode 100644
index 00000000..79f7ecab
--- /dev/null
+++ b/example/flutter/.gitignore
@@ -0,0 +1,48 @@
+# Miscellaneous
+*.class
+*.log
+*.pyc
+*.swp
+.DS_Store
+.atom/
+.build/
+.buildlog/
+.history
+.svn/
+.swiftpm/
+migrate_working_dir/
+
+# IntelliJ related
+*.iml
+*.ipr
+*.iws
+.idea/
+
+# The .vscode folder contains launch configuration and tasks you configure in
+# VS Code which you may wish to be included in version control, so this line
+# is commented out by default.
+#.vscode/
+
+# Flutter/Dart/Pub related
+**/doc/api/
+**/ios/Flutter/.last_build_id
+.dart_tool/
+.flutter-plugins-dependencies
+.pub-cache/
+.pub/
+/build/
+/coverage/
+
+# Symbolication related
+app.*.symbols
+
+# Obfuscation related
+app.*.map.json
+
+# Android Studio will place build artifacts here
+/android/app/debug
+/android/app/profile
+/android/app/release
+
+# Widget Preview related
+.widget_preview/
diff --git a/example/flutter/.metadata b/example/flutter/.metadata
new file mode 100644
index 00000000..c143d627
--- /dev/null
+++ b/example/flutter/.metadata
@@ -0,0 +1,30 @@
+# This file tracks properties of this Flutter project.
+# Used by Flutter tool to assess capabilities and perform upgrades etc.
+#
+# This file should be version controlled and should not be manually edited.
+
+version:
+ revision: "9584c6713b324636289d067944a46fd6b49df14b"
+ channel: "stable"
+
+project_type: app
+
+# Tracks metadata for the flutter migrate command
+migration:
+ platforms:
+ - platform: root
+ create_revision: 9584c6713b324636289d067944a46fd6b49df14b
+ base_revision: 9584c6713b324636289d067944a46fd6b49df14b
+ - platform: android
+ create_revision: 9584c6713b324636289d067944a46fd6b49df14b
+ base_revision: 9584c6713b324636289d067944a46fd6b49df14b
+
+ # User provided section
+
+ # List of Local paths (relative to this file) that should be
+ # ignored by the migrate tool.
+ #
+ # Files that are not part of the templates will be ignored by default.
+ unmanaged_files:
+ - 'lib/main.dart'
+ - 'ios/Runner.xcodeproj/project.pbxproj'
diff --git a/example/flutter/README.md b/example/flutter/README.md
new file mode 100644
index 00000000..ede746bf
--- /dev/null
+++ b/example/flutter/README.md
@@ -0,0 +1,80 @@
+# Flutter acceptance
+
+For Web, use the same package and SQLite entry point:
+
+```sh
+cd example/flutter
+flutter pub get
+flutter run -d chrome
+flutter build web --wasm
+```
+
+No worker compilation, WASM download or application asset declaration is needed.
+The Web example applies the fixed Dart migration history, persists a note and its
+comment in one transaction, loads typed relationships and checks that animation
+advances during worker SQL. Refreshing the page retains its OPFS database.
+The platform-specific acceptance files select different checks and host reporting;
+they do not implement database drivers.
+
+The automated release runner is `dart run tool/test_flutter_web.dart /path/to/flutter`
+from the repository root. For native directory choices and current platform limits,
+see [SQLite setup](../../docs/sqlite-web.md).
+
+## Android acceptance
+
+This Android application exercises the public ORM APIs in an installed Flutter
+app. The native bridge only provides the application's files directory and launch
+phase; SQLite executes through `package:orm/sqlite.dart` in its worker isolate.
+
+The legacy schema stores two notes. The current schema preserves the physical
+`body` column while exposing `text`, adds a defaulted `done` field and a related
+comments table. Both migrations are fixed Dart libraries with recorded fingerprints, imported
+through a static registry and compiled into the APK. No migration assets are loaded. The application
+checks generated CRUD, transaction rollback, relation projections, watch delivery,
+cancellation, read-only reopening and process persistence.
+
+Use a dedicated arm64 Android emulator. The runner rejects physical-device serials
+and an already-installed `dev.orm.orm_flutter`; it never clears application data.
+To repeat, explicitly uninstall that test app on your dedicated emulator or use a
+fresh emulator. No production database or physical device is involved.
+
+From the repository root, after choosing an installed Flutter SDK:
+
+```sh
+cd example/flutter
+flutter pub get
+flutter build apk --debug --target-platform android-arm64 \
+ --dart-define=ORM_SCHEMA_VERSION=1
+mkdir -p ../../.dart_tool/flutter
+cp build/app/outputs/flutter-apk/app-debug.apk ../../.dart_tool/flutter/legacy.apk
+flutter build apk --release --target-platform android-arm64 --build-number=2 \
+ --dart-define=ORM_SCHEMA_VERSION=2
+cp build/app/outputs/flutter-apk/app-release.apk ../../.dart_tool/flutter/current.apk
+cd ../..
+dart run tool/test_flutter.dart /path/to/android/sdk/platform-tools/adb \
+ emulator-5580 .dart_tool/flutter/legacy.apk .dart_tool/flutter/current.apk
+```
+
+The example uses Flutter's debug signing key for both APKs so `adb install -r`
+can preserve the database. These APKs are test artifacts, not store releases.
+The runner force-stops between phases, verifies distinct process IDs and matching
+database paths, compares rows and migration checksums after restart, and saves a
+machine-readable report at `research/validation/flutter.json`. Logs, individual
+reports and APK copies stay in `.dart_tool/flutter/`; the final screenshot is
+saved as `research/validation/flutter-android.png`.
+
+The application prints chunked base64 JSON so the host can capture release reports
+without `run-as`. SQL work runs while a Flutter animation and Dart timer advance;
+their progress verifies worker separation, not a frame-rate performance target.
+The acceptance scope is the tested Android emulator. iOS, macOS Flutter, physical
+devices and power-loss recovery require their own runs.
+
+To edit the schema, run the generator from the repository root after `pub get`:
+
+```sh
+dart run bin/orm.dart generate example/flutter/lib/legacy/schema.dart
+dart run bin/orm.dart generate example/flutter/lib/schema.dart
+```
+
+Do not regenerate applied migration history. Add a reviewed migration for future
+schema changes.
diff --git a/example/flutter/analysis_options.yaml b/example/flutter/analysis_options.yaml
new file mode 100644
index 00000000..5620c6d0
--- /dev/null
+++ b/example/flutter/analysis_options.yaml
@@ -0,0 +1,7 @@
+include: package:flutter_lints/flutter.yaml
+
+analyzer:
+ exclude:
+ - build/**
+ - android/**
+ - web/**
diff --git a/example/flutter/android/.gitignore b/example/flutter/android/.gitignore
new file mode 100644
index 00000000..be3943c9
--- /dev/null
+++ b/example/flutter/android/.gitignore
@@ -0,0 +1,14 @@
+gradle-wrapper.jar
+/.gradle
+/captures/
+/gradlew
+/gradlew.bat
+/local.properties
+GeneratedPluginRegistrant.java
+.cxx/
+
+# Remember to never publicly share your keystore.
+# See https://flutter.dev/to/reference-keystore
+key.properties
+**/*.keystore
+**/*.jks
diff --git a/example/flutter/android/app/build.gradle.kts b/example/flutter/android/app/build.gradle.kts
new file mode 100644
index 00000000..4d903648
--- /dev/null
+++ b/example/flutter/android/app/build.gradle.kts
@@ -0,0 +1,49 @@
+plugins {
+ id("com.android.application")
+ // The Flutter Gradle Plugin must be applied after the Android and Kotlin Gradle plugins.
+ id("dev.flutter.flutter-gradle-plugin")
+}
+
+android {
+ namespace = "dev.orm.orm_flutter"
+ compileSdk = flutter.compileSdkVersion
+ ndkVersion = flutter.ndkVersion
+
+ compileOptions {
+ sourceCompatibility = JavaVersion.VERSION_17
+ targetCompatibility = JavaVersion.VERSION_17
+ }
+
+ defaultConfig {
+ // TODO: Specify your own unique Application ID (https://developer.android.com/studio/build/application-id.html).
+ applicationId = "dev.orm.orm_flutter"
+ // You can update the following values to match your application needs.
+ // For more information, see: https://flutter.dev/to/review-gradle-config.
+ minSdk = flutter.minSdkVersion
+ targetSdk = flutter.targetSdkVersion
+ // Uses the version code from pubspec.yaml. When using split APKs, 1000 * ABI_VERSION
+ // is added automatically by Flutter. (https://developer.android.com/studio/build/configure-apk-splits#configure-APK-versions)
+ // You can force using the value of versionCode by specifying the `-P force-version-code-ignoring-abi=true`
+ // flag during build.
+ versionCode = flutter.versionCode
+ versionName = flutter.versionName
+ }
+
+ buildTypes {
+ release {
+ // TODO: Add your own signing config for the release build.
+ // Signing with the debug keys for now, so `flutter run --release` works.
+ signingConfig = signingConfigs.getByName("debug")
+ }
+ }
+}
+
+kotlin {
+ compilerOptions {
+ jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17
+ }
+}
+
+flutter {
+ source = "../.."
+}
diff --git a/example/flutter/android/app/src/debug/AndroidManifest.xml b/example/flutter/android/app/src/debug/AndroidManifest.xml
new file mode 100644
index 00000000..399f6981
--- /dev/null
+++ b/example/flutter/android/app/src/debug/AndroidManifest.xml
@@ -0,0 +1,7 @@
+
+
+
diff --git a/example/flutter/android/app/src/main/AndroidManifest.xml b/example/flutter/android/app/src/main/AndroidManifest.xml
new file mode 100644
index 00000000..1494326a
--- /dev/null
+++ b/example/flutter/android/app/src/main/AndroidManifest.xml
@@ -0,0 +1,45 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/example/flutter/android/app/src/main/kotlin/dev/orm/orm_flutter/MainActivity.kt b/example/flutter/android/app/src/main/kotlin/dev/orm/orm_flutter/MainActivity.kt
new file mode 100644
index 00000000..d26197d5
--- /dev/null
+++ b/example/flutter/android/app/src/main/kotlin/dev/orm/orm_flutter/MainActivity.kt
@@ -0,0 +1,24 @@
+package dev.orm.orm_flutter
+
+import io.flutter.embedding.android.FlutterActivity
+import io.flutter.embedding.engine.FlutterEngine
+import io.flutter.plugin.common.MethodChannel
+
+class MainActivity : FlutterActivity() {
+ override fun configureFlutterEngine(flutterEngine: FlutterEngine) {
+ super.configureFlutterEngine(flutterEngine)
+ MethodChannel(flutterEngine.dartExecutor.binaryMessenger, "orm_acceptance/config")
+ .setMethodCallHandler { call, result ->
+ if (call.method == "read") {
+ result.success(mapOf(
+ "filesPath" to filesDir.absolutePath,
+ "phase" to (intent.getStringExtra("orm_phase") ?: "upgrade"),
+ "api" to android.os.Build.VERSION.SDK_INT,
+ "pid" to android.os.Process.myPid()
+ ))
+ } else {
+ result.notImplemented()
+ }
+ }
+ }
+}
diff --git a/example/flutter/android/app/src/main/res/drawable-v21/launch_background.xml b/example/flutter/android/app/src/main/res/drawable-v21/launch_background.xml
new file mode 100644
index 00000000..f74085f3
--- /dev/null
+++ b/example/flutter/android/app/src/main/res/drawable-v21/launch_background.xml
@@ -0,0 +1,12 @@
+
+
+
+
diff --git a/example/flutter/android/app/src/main/res/drawable/launch_background.xml b/example/flutter/android/app/src/main/res/drawable/launch_background.xml
new file mode 100644
index 00000000..304732f8
--- /dev/null
+++ b/example/flutter/android/app/src/main/res/drawable/launch_background.xml
@@ -0,0 +1,12 @@
+
+
+
+
diff --git a/example/flutter/android/app/src/main/res/mipmap-hdpi/ic_launcher.png b/example/flutter/android/app/src/main/res/mipmap-hdpi/ic_launcher.png
new file mode 100644
index 00000000..db77bb4b
Binary files /dev/null and b/example/flutter/android/app/src/main/res/mipmap-hdpi/ic_launcher.png differ
diff --git a/example/flutter/android/app/src/main/res/mipmap-mdpi/ic_launcher.png b/example/flutter/android/app/src/main/res/mipmap-mdpi/ic_launcher.png
new file mode 100644
index 00000000..17987b79
Binary files /dev/null and b/example/flutter/android/app/src/main/res/mipmap-mdpi/ic_launcher.png differ
diff --git a/example/flutter/android/app/src/main/res/mipmap-xhdpi/ic_launcher.png b/example/flutter/android/app/src/main/res/mipmap-xhdpi/ic_launcher.png
new file mode 100644
index 00000000..09d43914
Binary files /dev/null and b/example/flutter/android/app/src/main/res/mipmap-xhdpi/ic_launcher.png differ
diff --git a/example/flutter/android/app/src/main/res/mipmap-xxhdpi/ic_launcher.png b/example/flutter/android/app/src/main/res/mipmap-xxhdpi/ic_launcher.png
new file mode 100644
index 00000000..d5f1c8d3
Binary files /dev/null and b/example/flutter/android/app/src/main/res/mipmap-xxhdpi/ic_launcher.png differ
diff --git a/example/flutter/android/app/src/main/res/mipmap-xxxhdpi/ic_launcher.png b/example/flutter/android/app/src/main/res/mipmap-xxxhdpi/ic_launcher.png
new file mode 100644
index 00000000..4d6372ee
Binary files /dev/null and b/example/flutter/android/app/src/main/res/mipmap-xxxhdpi/ic_launcher.png differ
diff --git a/example/flutter/android/app/src/main/res/values-night/styles.xml b/example/flutter/android/app/src/main/res/values-night/styles.xml
new file mode 100644
index 00000000..06952be7
--- /dev/null
+++ b/example/flutter/android/app/src/main/res/values-night/styles.xml
@@ -0,0 +1,18 @@
+
+
+
+
+
+
+
diff --git a/example/flutter/android/app/src/main/res/values/styles.xml b/example/flutter/android/app/src/main/res/values/styles.xml
new file mode 100644
index 00000000..cb1ef880
--- /dev/null
+++ b/example/flutter/android/app/src/main/res/values/styles.xml
@@ -0,0 +1,18 @@
+
+
+
+
+
+
+
diff --git a/example/flutter/android/app/src/profile/AndroidManifest.xml b/example/flutter/android/app/src/profile/AndroidManifest.xml
new file mode 100644
index 00000000..399f6981
--- /dev/null
+++ b/example/flutter/android/app/src/profile/AndroidManifest.xml
@@ -0,0 +1,7 @@
+
+
+
diff --git a/example/flutter/android/build.gradle.kts b/example/flutter/android/build.gradle.kts
new file mode 100644
index 00000000..dbee657b
--- /dev/null
+++ b/example/flutter/android/build.gradle.kts
@@ -0,0 +1,24 @@
+allprojects {
+ repositories {
+ google()
+ mavenCentral()
+ }
+}
+
+val newBuildDir: Directory =
+ rootProject.layout.buildDirectory
+ .dir("../../build")
+ .get()
+rootProject.layout.buildDirectory.value(newBuildDir)
+
+subprojects {
+ val newSubprojectBuildDir: Directory = newBuildDir.dir(project.name)
+ project.layout.buildDirectory.value(newSubprojectBuildDir)
+}
+subprojects {
+ project.evaluationDependsOn(":app")
+}
+
+tasks.register("clean") {
+ delete(rootProject.layout.buildDirectory)
+}
diff --git a/example/flutter/android/gradle.properties b/example/flutter/android/gradle.properties
new file mode 100644
index 00000000..e96108cf
--- /dev/null
+++ b/example/flutter/android/gradle.properties
@@ -0,0 +1,6 @@
+org.gradle.jvmargs=-Xmx8G -XX:MaxMetaspaceSize=4G -XX:ReservedCodeCacheSize=512m -XX:+HeapDumpOnOutOfMemoryError
+android.useAndroidX=true
+# This newDsl flag was added by the Flutter template
+android.newDsl=false
+# This builtInKotlin flag was added by the Flutter template
+android.builtInKotlin=false
diff --git a/example/flutter/android/gradle/wrapper/gradle-wrapper.properties b/example/flutter/android/gradle/wrapper/gradle-wrapper.properties
new file mode 100644
index 00000000..a20f2c46
--- /dev/null
+++ b/example/flutter/android/gradle/wrapper/gradle-wrapper.properties
@@ -0,0 +1,5 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-9.3.1-all.zip
diff --git a/example/flutter/android/settings.gradle.kts b/example/flutter/android/settings.gradle.kts
new file mode 100644
index 00000000..b28021a9
--- /dev/null
+++ b/example/flutter/android/settings.gradle.kts
@@ -0,0 +1,26 @@
+pluginManagement {
+ val flutterSdkPath =
+ run {
+ val properties = java.util.Properties()
+ file("local.properties").inputStream().use { properties.load(it) }
+ val flutterSdkPath = properties.getProperty("flutter.sdk")
+ require(flutterSdkPath != null) { "flutter.sdk not set in local.properties" }
+ flutterSdkPath
+ }
+
+ includeBuild("$flutterSdkPath/packages/flutter_tools/gradle")
+
+ repositories {
+ google()
+ mavenCentral()
+ gradlePluginPortal()
+ }
+}
+
+plugins {
+ id("dev.flutter.flutter-plugin-loader") version "1.0.0"
+ id("com.android.application") version "9.1.0" apply false
+ id("org.jetbrains.kotlin.android") version "2.4.0" apply false
+}
+
+include(":app")
diff --git a/example/flutter/lib/acceptance.dart b/example/flutter/lib/acceptance.dart
new file mode 100644
index 00000000..f0327f1d
--- /dev/null
+++ b/example/flutter/lib/acceptance.dart
@@ -0,0 +1,290 @@
+import 'dart:async';
+import 'dart:convert';
+import 'dart:io';
+
+import 'package:flutter/foundation.dart';
+import 'package:flutter/services.dart';
+import 'package:orm/migrate.dart';
+import 'package:orm/sqlite.dart';
+
+import 'legacy/seed.dart';
+import 'migrations/migrations.g.dart';
+import 'schema.orm.dart';
+
+typedef NoteCard = ({int id, String text, bool done, List comments});
+
+/// Runs inside the installed application, using its own persistent database.
+Future> runAcceptance({
+ required void Function(List) onRows,
+ required void Function(String) onCheck,
+ required int Function() frameCount,
+}) async {
+ const version = int.fromEnvironment('ORM_SCHEMA_VERSION', defaultValue: 2);
+ final config = (await const MethodChannel('orm_acceptance/config')
+ .invokeMapMethod('read'))!;
+ final phase = version == 1 ? 'legacy' : config['phase']! as String;
+ final path = '${config['filesPath']}/acceptance.sqlite';
+ final checks = [];
+ final report = {
+ 'phase': phase,
+ 'schemaVersion': version,
+ 'release': kReleaseMode,
+ 'dart': Platform.version,
+ 'os': Platform.operatingSystemVersion,
+ 'androidApi': config['api'],
+ 'pid': config['pid'],
+ 'path': path,
+ 'checks': checks,
+ };
+ void check(bool condition, String name) {
+ if (!condition) throw StateError(name);
+ checks.add(name);
+ onCheck(name);
+ }
+
+ Database? database;
+ StreamSubscription>? subscription;
+ try {
+ check(
+ await File(path).exists() == (phase != 'legacy'),
+ phase == 'legacy' ? 'Fresh database' : 'Existing database retained',
+ );
+ final migrations = migrationHistory.checked.take(version).toList();
+ final db = database = await sqlite(SqliteOptions.file(path));
+ report['sqlite'] = (await db.execute(SqlCommand('SELECT sqlite_version()')))
+ .rows
+ .single
+ .single;
+ if (phase == 'legacy') {
+ await seedLegacy(db, migrations.single);
+ final rows = (await db.execute(
+ SqlCommand('SELECT id, body, created_at FROM notes ORDER BY id'),
+ )).rows;
+ check(
+ rows.length == 2,
+ 'Version 1 typed transaction persisted two notes',
+ );
+ report['legacyRows'] = rows;
+ } else {
+ check(phase == 'upgrade' || phase == 'reopen', 'Known execution phase');
+ final before = await Migrator(db.sql).history();
+ check(
+ before.map((m) => m.id).join(',') ==
+ (phase == 'upgrade'
+ ? '0001_initial'
+ : '0001_initial,0002_comments'),
+ 'Expected previous migration history',
+ );
+ final applied = await Migrator(db.sql).apply(migrations);
+ check(
+ applied.join(',') == (phase == 'upgrade' ? '0002_comments' : ''),
+ phase == 'upgrade'
+ ? 'Only version 2 migration applied'
+ : 'No migration replay',
+ );
+ final schema = await verifySchema(db.sql, migrations.last.snapshot!);
+ check(schema.matches, 'Live schema matches bundled snapshot');
+ report['unmanaged'] = schema.unmanaged.map((o) => o.name).toList();
+ final original = await db.notes.byId(1).single();
+ check(
+ original.text == 'Written by version 1' &&
+ original.createdAt == DateTime.utc(2026, 9, 15, 1, 2, 3, 123, 456),
+ 'Original value and timestamp microseconds preserved',
+ );
+ check(
+ original.done == (phase == 'reopen'),
+ 'New field default / persisted update',
+ );
+ final query = db.notes
+ .orderBy((n) => [n.id.asc()])
+ .select(
+ (n) =>
+ (
+ n.id,
+ n.text,
+ n.done,
+ n.comments
+ .orderBy((c) => [c.id.asc()])
+ .select((c) => c.text)
+ .many(),
+ ).map(
+ (id, text, done, comments) =>
+ (id: id, text: text, done: done, comments: comments),
+ ),
+ );
+ final snapshots = >[];
+ Object? watchError;
+ subscription = query.watch().listen((rows) {
+ snapshots.add(rows);
+ onRows(rows);
+ }, onError: (Object error) => watchError = error);
+ Future waitFor(bool Function(List) predicate) async {
+ final deadline = DateTime.now().add(const Duration(seconds: 10));
+ while (snapshots.isEmpty || !predicate(snapshots.last)) {
+ if (watchError != null) throw watchError!;
+ if (DateTime.now().isAfter(deadline)) {
+ throw StateError('Watch timed out');
+ }
+ await Future.delayed(const Duration(milliseconds: 10));
+ }
+ }
+
+ await waitFor((rows) => rows.length == (phase == 'upgrade' ? 2 : 3));
+ check(true, 'Initial watch snapshot delivered to Flutter');
+ if (phase == 'upgrade') {
+ await db.transaction((tx) async {
+ final note = await tx.notes.create(
+ text: 'Written by version 2',
+ createdAt: DateTime.utc(2026, 9, 15, 2),
+ );
+ await tx.comments.create(
+ noteId: note.id,
+ text: 'Related in one transaction',
+ );
+ });
+ await waitFor(
+ (rows) => rows.length == 3 && rows.last.comments.length == 1,
+ );
+ check(true, 'Committed relation write refreshed watch');
+ final count = snapshots.length;
+ final rollback = StateError('Expected rollback');
+ try {
+ await db.transaction((tx) async {
+ await tx.notes.create(
+ text: 'Must roll back',
+ createdAt: DateTime.utc(2026),
+ );
+ throw rollback;
+ });
+ } catch (error) {
+ if (!identical(error, rollback)) rethrow;
+ }
+ await Future.delayed(const Duration(milliseconds: 200));
+ check(
+ snapshots.length == count && (await query.get()).length == 3,
+ 'Rollback neither persisted nor notified',
+ );
+ await db.notes.byId(1).patch(done: .set(true));
+ await waitFor((rows) => rows.first.done);
+ check(true, 'Typed patch refreshed watch');
+ var ticks = 0;
+ final timer = Timer.periodic(
+ const Duration(milliseconds: 16),
+ (_) => ticks++,
+ );
+ final framesBefore = frameCount();
+ final watch = Stopwatch()..start();
+ try {
+ final result = await db.execute(
+ SqlCommand(
+ 'WITH RECURSIVE n(x) AS (VALUES(1) UNION ALL SELECT x+1 FROM n WHERE x<2000000) SELECT sum(x) FROM n',
+ ),
+ options: const ExecutionOptions(timeout: Duration(seconds: 30)),
+ );
+ check(
+ result.rows.single.single == 2000001000000,
+ 'Background SQLite computation result',
+ );
+ } finally {
+ timer.cancel();
+ watch.stop();
+ }
+ report['background'] = {
+ 'elapsedUs': watch.elapsedMicroseconds,
+ 'timerTicks': ticks,
+ 'flutterFrames': frameCount() - framesBefore,
+ };
+ check(
+ ticks >= 3 && frameCount() - framesBefore >= 3,
+ 'Dart timer and Flutter frames advanced during SQLite work',
+ );
+ final token = CancellationToken();
+ final cancel = Timer(const Duration(milliseconds: 50), token.cancel);
+ String? cancellation;
+ try {
+ await db.execute(
+ SqlCommand(
+ 'WITH RECURSIVE n(x) AS (VALUES(1) UNION ALL SELECT x+1 FROM n WHERE x<100000000) SELECT sum(x) FROM n',
+ ),
+ options: ExecutionOptions(
+ cancellation: token,
+ timeout: const Duration(seconds: 30),
+ ),
+ );
+ } on OrmException catch (error) {
+ cancellation = error.code;
+ } finally {
+ cancel.cancel();
+ }
+ check(
+ cancellation == 'OPERATION.CANCELLED',
+ 'Native SQLite cancellation',
+ );
+ check(
+ (await query.get()).length == 3,
+ 'Worker usable after cancellation',
+ );
+ } else {
+ check(
+ snapshots.last.last.comments.single == 'Related in one transaction',
+ 'Relation data survived process restart',
+ );
+ }
+ report['watchSnapshots'] = snapshots.length;
+ report['rows'] = [
+ for (final n in await query.get())
+ {'id': n.id, 'text': n.text, 'done': n.done, 'comments': n.comments},
+ ];
+ await subscription.cancel();
+ subscription = null;
+ }
+ final versionState = await Migrator(db.sql).requireVersion(migrations);
+ check(
+ versionState.id == migrations.last.id,
+ 'Application schema compatibility',
+ );
+ report['history'] = [
+ for (final m in await Migrator(db.sql).history())
+ {'id': m.id, 'checksum': m.checksum},
+ ];
+ await db.close();
+ database = null;
+ final reader = await sqlite(SqliteOptions.readOnly(path));
+ try {
+ check(
+ (await reader.execute(SqlCommand('SELECT count(*) FROM notes')))
+ .rows
+ .single
+ .single ==
+ (phase == 'legacy' ? 2 : 3),
+ 'Closed database reopened read-only',
+ );
+ } finally {
+ await reader.close();
+ }
+ report['status'] = 'passed';
+ } catch (error, stack) {
+ report['status'] = 'failed';
+ report['error'] = '$error';
+ report['stack'] = '$stack';
+ } finally {
+ await subscription?.cancel();
+ await database?.close();
+ }
+ final json = jsonEncode(report);
+ await File('${config['filesPath']}/$phase.json')
+ .writeAsString(json, flush: true);
+ final encoded = base64Encode(utf8.encode(json));
+ // The Android Flutter log sink truncated 1,800-character chunks in release.
+ const size = 700;
+ final count = (encoded.length / size).ceil();
+ for (var i = 0; i < count; i++) {
+ final end = (i + 1) * size;
+ // Machine-readable transport also works in release builds without run-as.
+ // ignore: avoid_print
+ print(
+ 'ORM_ACCEPTANCE $phase ${i + 1}/$count ${encoded.substring(i * size, end > encoded.length ? encoded.length : end)}',
+ );
+ }
+ return report;
+}
diff --git a/example/flutter/lib/acceptance_web.dart b/example/flutter/lib/acceptance_web.dart
new file mode 100644
index 00000000..2798587f
--- /dev/null
+++ b/example/flutter/lib/acceptance_web.dart
@@ -0,0 +1,95 @@
+import 'package:flutter/foundation.dart';
+import 'package:orm/migrate.dart';
+import 'package:orm/sqlite.dart';
+
+import 'migrations/migrations.g.dart';
+import 'schema.orm.dart';
+
+typedef NoteCard = ({int id, String text, bool done, List comments});
+
+Future> runAcceptance({
+ required void Function(List) onRows,
+ required void Function(String) onCheck,
+ required int Function() frameCount,
+}) async {
+ final report = {
+ 'phase': 'web',
+ 'release': kReleaseMode,
+ 'sqlite': 'opening',
+ };
+ Database? database;
+ void check(bool condition, String name) {
+ if (!condition) throw StateError(name);
+ onCheck(name);
+ }
+
+ try {
+ final db = database = await sqlite(
+ const SqliteOptions.persistent('flutter-example'),
+ );
+ report['sqlite'] = (await db.execute(SqlCommand('SELECT sqlite_version()')))
+ .rows
+ .single
+ .single;
+ await Migrator(db.sql).apply(migrationHistory.checked);
+ check(
+ (await verifySchema(
+ db.sql,
+ migrationHistory.checked.last.snapshot!,
+ )).matches,
+ 'Bundled Dart migrations match the browser database',
+ );
+ if (await db.notes.count() == 0) {
+ await db.transaction((tx) async {
+ final note = await tx.notes.create(
+ text: 'Stored in the browser',
+ createdAt: DateTime.now().toUtc(),
+ );
+ await tx.comments.create(
+ noteId: note.id,
+ text: 'Written in the same transaction',
+ );
+ });
+ }
+ final rows = await db.notes
+ .orderBy((n) => [n.id.asc()])
+ .select(
+ (n) =>
+ (
+ n.id,
+ n.text,
+ n.done,
+ n.comments
+ .orderBy((c) => [c.id.asc()])
+ .select((c) => c.text)
+ .many(),
+ ).map(
+ (id, text, done, comments) =>
+ (id: id, text: text, done: done, comments: comments),
+ ),
+ )
+ .get();
+ onRows(rows);
+ check(
+ rows.isNotEmpty && rows.first.comments.isNotEmpty,
+ 'Typed records and relationships loaded into Flutter',
+ );
+ final frames = frameCount();
+ await db.execute(
+ SqlCommand(
+ 'WITH RECURSIVE n(x) AS (VALUES(1) UNION ALL SELECT x+1 FROM n WHERE x<1000000) SELECT SUM(x) FROM n',
+ ),
+ );
+ check(
+ frameCount() > frames,
+ 'Flutter animation advanced during worker SQL',
+ );
+ report['status'] = 'passed';
+ } catch (error) {
+ report['status'] = 'failed';
+ report['error'] = error.toString();
+ } finally {
+ await database?.close();
+ }
+ return report;
+}
diff --git a/example/flutter/lib/legacy/schema.dart b/example/flutter/lib/legacy/schema.dart
new file mode 100644
index 00000000..ba0d8ba5
--- /dev/null
+++ b/example/flutter/lib/legacy/schema.dart
@@ -0,0 +1,4 @@
+import 'package:orm/schema.dart';
+
+typedef Note = ({@Id.generated() int id, String body, DateTime createdAt});
+final notes = entity(table: 'notes');
diff --git a/example/flutter/lib/legacy/schema.orm.dart b/example/flutter/lib/legacy/schema.orm.dart
new file mode 100644
index 00000000..6d7ad8bc
--- /dev/null
+++ b/example/flutter/lib/legacy/schema.orm.dart
@@ -0,0 +1,83 @@
+// GENERATED CODE - DO NOT MODIFY BY HAND.
+
+import 'package:orm/sql.dart';
+
+import "schema.dart" as models;
+export "schema.dart" show Note;
+
+final _notesId = Column(
+ "id",
+ Codecs.integer,
+ nullable: false,
+ generated: true,
+);
+final _notesBody = Column(
+ "body",
+ Codecs.text,
+ nullable: false,
+ generated: false,
+);
+final _notesCreatedAt = Column(
+ "created_at",
+ Codecs.dateTime,
+ nullable: false,
+ generated: false,
+);
+final notesSchema = TableSchema(
+ "notes",
+ columns: [_notesId, _notesBody, _notesCreatedAt],
+ primaryKey: ["id"],
+ uniqueKeys: [],
+ indexes: [],
+ foreignKeys: [],
+);
+
+final class NotesFields extends Fields {
+ NotesFields(super.table);
+ late final id = column(_notesId);
+ late final body = column(_notesBody);
+ late final createdAt = column(_notesCreatedAt);
+}
+
+final notesTable = Table(
+ notesSchema,
+ NotesFields.new,
+ (row) => (
+ row.id,
+ row.body,
+ row.createdAt,
+ ).map((id, body, createdAt) => (id: id, body: body, createdAt: createdAt)),
+);
+
+final class NotesTableSet extends TableSet {
+ NotesTableSet(QueryContext db) : super(db, notesTable) {
+ db.registerSchema(appSchema);
+ }
+ Future
-
-