Skip to content

popoto.backends.postgres.recipes

popoto.backends.postgres.recipes

The recipe-layer field_call adapters on Postgres (#759 M4; plan §2 H).

The recipes reach storage through field and model methods (#630), and a few of those methods keep state outside any model's hash on Redis: a counter string, the tombstone archive and negative prior, the question queue's token bucket and propose lock, OBJECT IDLETIME, and the ZCARD / ZRANGE / ZSCORE reads of a sorted field's partition. On a Postgres-bound model each is a field_call adapter here, keyed by a pseudo-field (_counter, _tomb, _tombprior, _qq, _idle) or, for the sorted reads, by the field itself:

============= ============================================================= adapter Postgres ============= ============================================================= _idle idle_seconds: whole seconds since the later of the row's _updated_at (its last write) and _last_accessed (its last confirmed read, AccessTrackerMixin); None with no row. Redis's OBJECT IDLETIME also resets on an unconfirmed read (any HGETALL) -- a documented divergence. sorted count / members / score on a sorted field: the partition's rows with a value, ordered by (value, _pk COLLATE "C") -- the sorted set's (score, member) order -- ZRANGE's inclusive and negative ranks included. _counter counters.increment / read on one engine table, popoto_counter (key, value): INSERT … ON CONFLICT DO UPDATE … RETURNING is INCRBY. _tomb TombstoneStore: popoto_tombstone (model, member, entry, ts), the data hash and recency index as one row per member. _tombprior TombstonePriorStore: popoto_tombstone_prior (model, digest, burials, ts) and popoto_tombstone_stats. _qq the question queue: deliver (_DELIVER_LUA), claim (_CLAIM_LUA), lock / release (the propose lock's SET NX PX and _RELEASE_LUA) over the candidate table, popoto_question_bucket (agent, last_turn, expires_at) and popoto_lease (key, token, expires_at). _lease lock / release: the same two ops, for any caller that needs a TTL lease (the decision log's assembly claim, #811). _qq keeps its pair; both names run one implementation. _m3 the decision log (#811): terminal_write (the guarded upsert that replaces TERMINAL_WRITE_LUA) and turn_summary (the aggregate that replaces the per-turn summary hash). _harness the harness integration's session state (#814): MemoryService's read-to-write handoff, its per-session injection suppression and its last-success timestamps, on popoto_harness_pending, popoto_harness_injected and popoto_harness_event. Its counters are _counter rows (scan and set_if_absent read and seed them by key prefix), so the DefaultMemory eviction counter and the integration's own counters live in one table, as they share one key prefix on Redis. ============= =============================================================

The engine tables are created on first use under pg_advisory_xact_lock, like popoto_recall_proposal: the schema's DDL lock first, as ensure_table takes it, then the table's (schema.engine_table_ddl), so concurrent first uses serialise on CREATE SCHEMA. They carry the same caveat on a shared schema: they are keyed by model name.

Delivery. _DELIVER_LUA grants the agent's one ask per K turns and claims a candidate in one atomic step. Here that step is one statement behind the agent's bucket advisory lock (so two deliveries for one agent serialize: the budget is exact under any concurrency); the candidates are tried in the caller's preference order with FOR UPDATE SKIP LOCKED, the first still deliverable and past its cooldown is flipped to delivered, and the bucket is written only when that claim succeeds. The statement waits on nothing but the bucket lock, which no record writer takes, so it cannot join a deadlock cycle; the cost is that a candidate a concurrent writer holds at that instant is skipped, as a candidate another worker claimed is skipped on Redis (a documented divergence: on Redis the script would wait its turn and see it).

HARNESS_REAP_BATCH = 20 module-attribute

Expired harness rows (abandoned sessions) a write deletes in passing. Every read filters expired rows, so this bounds only how long a dead session's rows occupy the table, never what a reader sees; the same batch size, for the same reason, as Defaults.PG_REAPER_BATCH for Meta.ttl tables.

RecipeOpsMixin

The adapters above, for :class:~popoto.backends.postgres.PostgresBackend.

Source code in src/popoto/backends/postgres/recipes.py
 177
 178
 179
 180
 181
 182
 183
 184
 185
 186
 187
 188
 189
 190
 191
 192
 193
 194
 195
 196
 197
 198
 199
 200
 201
 202
 203
 204
 205
 206
 207
 208
 209
 210
 211
 212
 213
 214
 215
 216
 217
 218
 219
 220
 221
 222
 223
 224
 225
 226
 227
 228
 229
 230
 231
 232
 233
 234
 235
 236
 237
 238
 239
 240
 241
 242
 243
 244
 245
 246
 247
 248
 249
 250
 251
 252
 253
 254
 255
 256
 257
 258
 259
 260
 261
 262
 263
 264
 265
 266
 267
 268
 269
 270
 271
 272
 273
 274
 275
 276
 277
 278
 279
 280
 281
 282
 283
 284
 285
 286
 287
 288
 289
 290
 291
 292
 293
 294
 295
 296
 297
 298
 299
 300
 301
 302
 303
 304
 305
 306
 307
 308
 309
 310
 311
 312
 313
 314
 315
 316
 317
 318
 319
 320
 321
 322
 323
 324
 325
 326
 327
 328
 329
 330
 331
 332
 333
 334
 335
 336
 337
 338
 339
 340
 341
 342
 343
 344
 345
 346
 347
 348
 349
 350
 351
 352
 353
 354
 355
 356
 357
 358
 359
 360
 361
 362
 363
 364
 365
 366
 367
 368
 369
 370
 371
 372
 373
 374
 375
 376
 377
 378
 379
 380
 381
 382
 383
 384
 385
 386
 387
 388
 389
 390
 391
 392
 393
 394
 395
 396
 397
 398
 399
 400
 401
 402
 403
 404
 405
 406
 407
 408
 409
 410
 411
 412
 413
 414
 415
 416
 417
 418
 419
 420
 421
 422
 423
 424
 425
 426
 427
 428
 429
 430
 431
 432
 433
 434
 435
 436
 437
 438
 439
 440
 441
 442
 443
 444
 445
 446
 447
 448
 449
 450
 451
 452
 453
 454
 455
 456
 457
 458
 459
 460
 461
 462
 463
 464
 465
 466
 467
 468
 469
 470
 471
 472
 473
 474
 475
 476
 477
 478
 479
 480
 481
 482
 483
 484
 485
 486
 487
 488
 489
 490
 491
 492
 493
 494
 495
 496
 497
 498
 499
 500
 501
 502
 503
 504
 505
 506
 507
 508
 509
 510
 511
 512
 513
 514
 515
 516
 517
 518
 519
 520
 521
 522
 523
 524
 525
 526
 527
 528
 529
 530
 531
 532
 533
 534
 535
 536
 537
 538
 539
 540
 541
 542
 543
 544
 545
 546
 547
 548
 549
 550
 551
 552
 553
 554
 555
 556
 557
 558
 559
 560
 561
 562
 563
 564
 565
 566
 567
 568
 569
 570
 571
 572
 573
 574
 575
 576
 577
 578
 579
 580
 581
 582
 583
 584
 585
 586
 587
 588
 589
 590
 591
 592
 593
 594
 595
 596
 597
 598
 599
 600
 601
 602
 603
 604
 605
 606
 607
 608
 609
 610
 611
 612
 613
 614
 615
 616
 617
 618
 619
 620
 621
 622
 623
 624
 625
 626
 627
 628
 629
 630
 631
 632
 633
 634
 635
 636
 637
 638
 639
 640
 641
 642
 643
 644
 645
 646
 647
 648
 649
 650
 651
 652
 653
 654
 655
 656
 657
 658
 659
 660
 661
 662
 663
 664
 665
 666
 667
 668
 669
 670
 671
 672
 673
 674
 675
 676
 677
 678
 679
 680
 681
 682
 683
 684
 685
 686
 687
 688
 689
 690
 691
 692
 693
 694
 695
 696
 697
 698
 699
 700
 701
 702
 703
 704
 705
 706
 707
 708
 709
 710
 711
 712
 713
 714
 715
 716
 717
 718
 719
 720
 721
 722
 723
 724
 725
 726
 727
 728
 729
 730
 731
 732
 733
 734
 735
 736
 737
 738
 739
 740
 741
 742
 743
 744
 745
 746
 747
 748
 749
 750
 751
 752
 753
 754
 755
 756
 757
 758
 759
 760
 761
 762
 763
 764
 765
 766
 767
 768
 769
 770
 771
 772
 773
 774
 775
 776
 777
 778
 779
 780
 781
 782
 783
 784
 785
 786
 787
 788
 789
 790
 791
 792
 793
 794
 795
 796
 797
 798
 799
 800
 801
 802
 803
 804
 805
 806
 807
 808
 809
 810
 811
 812
 813
 814
 815
 816
 817
 818
 819
 820
 821
 822
 823
 824
 825
 826
 827
 828
 829
 830
 831
 832
 833
 834
 835
 836
 837
 838
 839
 840
 841
 842
 843
 844
 845
 846
 847
 848
 849
 850
 851
 852
 853
 854
 855
 856
 857
 858
 859
 860
 861
 862
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
class RecipeOpsMixin:
    """The adapters above, for
    :class:`~popoto.backends.postgres.PostgresBackend`."""

    schema: str
    _table: Callable[..., Any]
    _run: Callable[..., tuple[list[tuple[Any, ...]], int]]
    _record_locked: Callable[..., tuple[str, list[Any]]]
    _ensure_engine_table: Callable[..., None]
    _row_values: Callable[..., dict[str, Any]]
    _after_write: Callable[..., None]

    # -- engine tables ------------------------------------------------------------

    def _engine(self, name: str) -> str:
        """``<schema>.<name>``, created on first use in this process (and
        again after :meth:`forget_tables`)."""
        qualified = f"{quote_ident(self.schema)}.{quote_ident(name)}"
        ready: set[str] = self.__dict__.setdefault("_engine_ready", set())
        if name in ready:
            return qualified
        # First-use DDL never takes a pooled connection inside a unit of
        # work (#776, PostgresBackend._ensure_engine_table). The schema lock
        # comes first in the DDL, as ensure_table takes it: a per-table lock
        # alone lets two first uses race on CREATE SCHEMA (B1).
        self._ensure_engine_table(
            "SELECT 1 FROM pg_tables WHERE schemaname = %s AND tablename = %s",
            [self.schema, name],
            bool,
            lambda: engine_table_ddl(self.schema, name, ENGINE_TABLES[name]),
            f"{self.schema}.{name} does not exist",
        )
        ready.add(name)
        return qualified

    # -- dispatch -----------------------------------------------------------------

    def _recipe_field_call(
        self,
        spec: ModelSpec,
        field: str,
        op: str,
        args: tuple[Any, ...],
        kwargs: dict[str, Any],
        uow: Optional[UnitOfWork],
    ) -> Any:
        handlers: Mapping[str, Callable[..., Any]] = {}
        if field == IDLE_FIELD:
            handlers = {"seconds": self._idle_seconds}
        elif field == COUNTER_FIELD:
            handlers = {
                "increment": self._counter_increment,
                "read": self._counter_read,
                "scan": self._counter_scan,
                "set_if_absent": self._counter_set_if_absent,
            }
        elif field == TOMB_FIELD:
            handlers = {
                "archive": self._tomb_archive,
                "count": self._tomb_count,
                "oldest": self._tomb_oldest,
                "newest": self._tomb_newest,
                "evict": self._tomb_evict,
                "entries": self._tomb_entries,
                "purge": self._tomb_purge,
                "purge_all": self._tomb_purge_all,
            }
        elif field == TOMBPRIOR_FIELD:
            handlers = {
                "bury": self._prior_bury,
                "burials": self._prior_burials,
                "penalty": self._prior_penalty,
                "stats": self._prior_stats,
                "count": self._prior_count,
                "purge_all": self._prior_purge_all,
            }
        elif field == EMBED_CACHE_FIELD:
            handlers = {
                "get": self._embed_cache_get,
                "set": self._embed_cache_set,
                "drop": self._embed_cache_drop,
            }
        elif field == NEVER_RECORD_FIELD:
            handlers = {
                "drop": self._nr_drop,
                "counts": self._nr_counts,
                "log": self._nr_log,
            }
        elif field == QQ_FIELD:
            handlers = {
                "deliver": self._qq_deliver,
                "claim": self._qq_claim,
                "lock": self._lease_lock,
                "release": self._lease_release,
            }
        elif field == LEASE_FIELD:
            handlers = {
                "lock": self._lease_lock,
                "release": self._lease_release,
            }
        elif field == M3_FIELD:
            handlers = {
                "terminal_write": self._m3_terminal_write,
                "turn_summary": self._m3_turn_summary,
            }
        elif field == HARNESS_FIELD:
            handlers = {
                "pending_push": self._harness_pending_push,
                "pending_claim": self._harness_pending_claim,
                "pending_pop": self._harness_pending_pop,
                "injected_read": self._harness_injected_read,
                "injected_mark": self._harness_injected_mark,
                "touch": self._harness_touch,
                "events": self._harness_events,
                "purge": self._harness_purge,
            }
        else:
            fs = spec.fields.get(field)
            if fs is not None and fs.kind in SORTED_KINDS:
                handlers = {
                    "count": self._sorted_count,
                    "members": self._sorted_members,
                    "score": self._sorted_score,
                }
        handler = handlers.get(op)
        if handler is None:
            return _NOT_HANDLED
        if field in (
            COUNTER_FIELD,
            TOMB_FIELD,
            TOMBPRIOR_FIELD,
            NEVER_RECORD_FIELD,
            EMBED_CACHE_FIELD,
            HARNESS_FIELD,
        ):
            # Model-level stores: the field name carries no information.
            return handler(spec, *args, uow=uow, **kwargs)
        return handler(spec, field, *args, uow=uow, **kwargs)

    # -- idle_seconds -------------------------------------------------------------

    def _idle_seconds(
        self,
        spec: ModelSpec,
        field: str,
        id: RecordId,
        *,
        uow: Optional[UnitOfWork] = None,
    ) -> Optional[float]:
        ts = self._table(spec)
        last = (
            'greatest(extract(epoch from "_updated_at"), coalesce("_last_accessed", '
            "'-Infinity'::float8))"
            if "_last_accessed" in {c.name for c in ts.columns}
            else 'extract(epoch from "_updated_at")'
        )
        from .ttl import live_sql

        # M5: an expired record has no idle time, as OBJECT IDLETIME of a key
        # Redis expired is nil.
        live = live_sql(ts)
        rows, _ = self._run(
            f"SELECT floor(greatest({_NOW} - {last}, 0))::float8 "
            f'FROM {ts.qualified} WHERE "_pk" = %s' + (f" AND {live}" if live else ""),
            [id.canonical],
            uow=uow,
        )
        return None if not rows else float(rows[0][0])

    # -- a sorted field's partition --------------------------------------------------

    def _partition_sql(
        self, ts: Any, spec: ModelSpec, field: str, partition: Mapping[str, Any]
    ) -> tuple[str, list[Any]]:
        from .memory import partition_where
        from .plan import render_where

        kinds = {name: fs.kind for name, fs in spec.fields.items()}
        sql, params = render_where(ts, kinds, partition_where(partition))
        col = f"t.{quote_ident(field)}"
        where = f" WHERE {col} IS NOT NULL"
        if sql:
            where += " AND " + sql[len(" WHERE ") :]
        return where, params

    def _sorted_count(
        self,
        spec: ModelSpec,
        field: str,
        partition: Mapping[str, Any],
        *,
        uow: Optional[UnitOfWork] = None,
    ) -> int:
        """``ZCARD`` of the partition: rows holding a value."""
        ts = self._table(spec)
        where, params = self._partition_sql(ts, spec, field, partition)
        rows, _ = self._run(
            f"SELECT count(*) FROM {ts.qualified} AS t{where}", params, uow=uow
        )
        return int(rows[0][0])

    def _sorted_members(
        self,
        spec: ModelSpec,
        field: str,
        partition: Mapping[str, Any],
        start: int,
        stop: int,
        reverse: bool,
        *,
        uow: Optional[UnitOfWork] = None,
    ) -> list[str]:
        """``ZRANGE`` / ``ZREVRANGE start stop``: inclusive ranks, negative
        ones counted from the end, ``(value, _pk)`` order (reversed: both
        descending)."""
        start, stop = int(start), int(stop)
        if start < 0 or stop < 0:
            n = self._sorted_count(spec, field, partition, uow=uow)
            start = max(start + n, 0) if start < 0 else start
            stop = stop + n if stop < 0 else stop
        if stop < start or stop < 0:
            return []
        ts = self._table(spec)
        where, params = self._partition_sql(ts, spec, field, partition)
        direction = "DESC" if reverse else "ASC"
        col = f"t.{quote_ident(field)}"
        rows, _ = self._run(
            f'SELECT t."_pk" FROM {ts.qualified} AS t{where} '
            f'ORDER BY {col} {direction}, t."_pk" COLLATE "C" {direction} '
            f"OFFSET {start} LIMIT {stop - start + 1}",
            params,
            uow=uow,
        )
        return [row[0] for row in rows]

    def _sorted_score(
        self,
        spec: ModelSpec,
        field: str,
        partition: Optional[Mapping[str, Any]],
        id: RecordId,
        *,
        uow: Optional[UnitOfWork] = None,
    ) -> Optional[Any]:
        """``ZSCORE``: the member's stored value, when the record is in the
        partition (``partition=None`` for the unpartitioned key, which a
        partitioned field's member is never in -- as on Redis). The caller
        converts it to the sorted set's score."""
        if partition is None and spec.fields[field].options.get("partition_by"):
            return None
        ts = self._table(spec)
        where, params = self._partition_sql(ts, spec, field, partition or {})
        rows, _ = self._run(
            f"SELECT t.{quote_ident(field)} FROM {ts.qualified} AS t{where} "
            'AND t."_pk" = %s',
            params + [id.canonical],
            uow=uow,
        )
        return rows[0][0] if rows else None

    # -- counters -------------------------------------------------------------------

    def _counter_increment(
        self, spec: ModelSpec, key: str, delta: int, *, uow: Optional[UnitOfWork] = None
    ) -> int:
        table = self._engine("popoto_counter")
        rows, _ = self._run(
            f"INSERT INTO {table} AS c (key, value) VALUES (%s, %s) "
            "ON CONFLICT (key) DO UPDATE SET value = c.value + EXCLUDED.value "
            "RETURNING c.value",
            [key, int(delta)],
            uow=uow,
            write=True,
        )
        return int(rows[0][0])

    def _counter_read(
        self, spec: ModelSpec, key: str, *, uow: Optional[UnitOfWork] = None
    ) -> int:
        table = self._engine("popoto_counter")
        rows, _ = self._run(f"SELECT value FROM {table} WHERE key = %s", [key], uow=uow)
        return int(rows[0][0]) if rows else 0

    def _counter_scan(
        self, spec: ModelSpec, prefix: str, *, uow: Optional[UnitOfWork] = None
    ) -> dict[str, int]:
        """Every counter whose key starts with ``prefix``: what
        ``SCAN MATCH <prefix>*`` plus a ``GET`` per key reads on Redis, as one
        snapshot rather than a key-by-key walk."""
        table = self._engine("popoto_counter")
        rows, _ = self._run(
            f"SELECT key, value FROM {table} WHERE starts_with(key, %s)",
            [prefix],
            uow=uow,
        )
        return {str(key): int(value) for key, value in rows}

    def _counter_set_if_absent(
        self,
        spec: ModelSpec,
        key: str,
        value: int,
        *,
        uow: Optional[UnitOfWork] = None,
    ) -> bool:
        """``SETNX key value``: ``True`` when this call created the counter."""
        table = self._engine("popoto_counter")
        rows, _ = self._run(
            f"INSERT INTO {table} (key, value) VALUES (%s, %s) "
            "ON CONFLICT (key) DO NOTHING RETURNING 1",
            [key, int(value)],
            uow=uow,
            write=True,
        )
        return bool(rows)

    # -- TombstoneStore ---------------------------------------------------------------

    def _tomb_archive(
        self,
        spec: ModelSpec,
        member: str,
        entry: bytes,
        ts: float,
        *,
        uow: Optional[UnitOfWork] = None,
    ) -> None:
        table = self._engine("popoto_tombstone")
        self._run(
            f"INSERT INTO {table} (model, member, entry, ts) VALUES (%s, %s, %s, %s) "
            "ON CONFLICT (model, member) DO UPDATE SET entry = EXCLUDED.entry, "
            "ts = EXCLUDED.ts",
            [spec.name, member, bytes(entry), float(ts)],
            uow=uow,
            write=True,
        )

    def _tomb_count(self, spec: ModelSpec, *, uow: Optional[UnitOfWork] = None) -> int:
        table = self._engine("popoto_tombstone")
        rows, _ = self._run(
            f"SELECT count(*) FROM {table} WHERE model = %s", [spec.name], uow=uow
        )
        return int(rows[0][0])

    def _tomb_ranked(self, spec: ModelSpec, n: int, desc: bool) -> list[str]:
        if n <= 0:
            return []
        table = self._engine("popoto_tombstone")
        order = "DESC" if desc else "ASC"
        rows, _ = self._run(
            f"SELECT member FROM {table} WHERE model = %s "
            f'ORDER BY ts {order}, member COLLATE "C" {order} LIMIT {int(n)}',
            [spec.name],
        )
        return [r[0] for r in rows]

    def _tomb_oldest(
        self, spec: ModelSpec, n: int, *, uow: Optional[UnitOfWork] = None
    ) -> list[str]:
        """``ZRANGE index 0 n-1``."""
        return self._tomb_ranked(spec, int(n), False)

    def _tomb_newest(
        self, spec: ModelSpec, stop: int, *, uow: Optional[UnitOfWork] = None
    ) -> list[str]:
        """``ZREVRANGE index 0 stop`` (``stop=-1``: all)."""
        stop = int(stop)
        if stop < 0:
            n = self._tomb_count(spec) + stop + 1
        else:
            n = stop + 1
        return self._tomb_ranked(spec, n, True)

    def _tomb_evict(
        self,
        spec: ModelSpec,
        members: Sequence[str],
        *,
        uow: Optional[UnitOfWork] = None,
    ) -> int:
        table = self._engine("popoto_tombstone")
        _, count = self._run(
            f"DELETE FROM {table} WHERE model = %s AND member = ANY(%s::text[])",
            [spec.name, list(members)],
            uow=uow,
            write=True,
        )
        return int(count or 0)

    def _tomb_entries(
        self,
        spec: ModelSpec,
        members: Sequence[str],
        *,
        uow: Optional[UnitOfWork] = None,
    ) -> list[Optional[bytes]]:
        """``HMGET``: entries in ``members`` order, ``None`` for a hole."""
        members = list(members)
        if not members:
            return []
        table = self._engine("popoto_tombstone")
        rows, _ = self._run(
            f"SELECT member, entry FROM {table} WHERE model = %s "
            "AND member = ANY(%s::text[])",
            [spec.name, members],
            uow=uow,
        )
        found = {m: bytes(e) for m, e in rows}
        return [found.get(m) for m in members]

    def _tomb_purge(
        self, spec: ModelSpec, member: str, *, uow: Optional[UnitOfWork] = None
    ) -> bool:
        return bool(self._tomb_evict(spec, [member], uow=uow))

    def _tomb_purge_all(
        self, spec: ModelSpec, *, uow: Optional[UnitOfWork] = None
    ) -> int:
        table = self._engine("popoto_tombstone")
        _, count = self._run(
            f"DELETE FROM {table} WHERE model = %s", [spec.name], uow=uow, write=True
        )
        return int(count or 0)

    # -- TombstonePriorStore ----------------------------------------------------------

    def _prior_bury(
        self,
        spec: ModelSpec,
        digest: str,
        ts: float,
        limit: int,
        *,
        uow: Optional[UnitOfWork] = None,
    ) -> int:
        """``HINCRBY`` + ``ZADD``, then the retention sweep (the oldest
        digests past ``limit``); returns how many were aged out."""
        table = self._engine("popoto_tombstone_prior")
        self._run(
            f"INSERT INTO {table} AS p (model, digest, burials, ts) "
            "VALUES (%s, %s, 1, %s) ON CONFLICT (model, digest) DO UPDATE "
            "SET burials = p.burials + 1, ts = EXCLUDED.ts",
            [spec.name, digest, float(ts)],
            uow=uow,
            write=True,
        )
        _, count = self._run(
            f"DELETE FROM {table} WHERE model = %s AND digest IN ("
            f"SELECT digest FROM {table} WHERE model = %s "
            'ORDER BY ts, digest COLLATE "C" LIMIT greatest(('
            f"SELECT count(*) FROM {table} WHERE model = %s) - %s, 0))",
            [spec.name, spec.name, spec.name, int(limit)],
            uow=uow,
            write=True,
        )
        return int(count or 0)

    def _prior_burials(
        self, spec: ModelSpec, digest: str, *, uow: Optional[UnitOfWork] = None
    ) -> int:
        table = self._engine("popoto_tombstone_prior")
        rows, _ = self._run(
            f"SELECT burials FROM {table} WHERE model = %s AND digest = %s",
            [spec.name, digest],
            uow=uow,
        )
        return int(rows[0][0]) if rows else 0

    def _prior_penalty(
        self,
        spec: ModelSpec,
        drawdown: float,
        *,
        uow: Optional[UnitOfWork] = None,
    ) -> None:
        table = self._engine("popoto_tombstone_stats")
        self._run(
            f"INSERT INTO {table} AS s (model, penalized, drawdown_total) "
            "VALUES (%s, 1, %s) ON CONFLICT (model) DO UPDATE SET "
            "penalized = s.penalized + 1, "
            "drawdown_total = s.drawdown_total + EXCLUDED.drawdown_total",
            [spec.name, float(drawdown)],
            uow=uow,
            write=True,
        )

    def _prior_stats(
        self, spec: ModelSpec, *, uow: Optional[UnitOfWork] = None
    ) -> Optional[tuple[int, float]]:
        table = self._engine("popoto_tombstone_stats")
        rows, _ = self._run(
            f"SELECT penalized, drawdown_total FROM {table} WHERE model = %s",
            [spec.name],
            uow=uow,
        )
        return (int(rows[0][0]), float(rows[0][1])) if rows else None

    def _prior_count(self, spec: ModelSpec, *, uow: Optional[UnitOfWork] = None) -> int:
        table = self._engine("popoto_tombstone_prior")
        rows, _ = self._run(
            f"SELECT count(*) FROM {table} WHERE model = %s", [spec.name], uow=uow
        )
        return int(rows[0][0])

    def _prior_purge_all(
        self, spec: ModelSpec, *, uow: Optional[UnitOfWork] = None
    ) -> int:
        prior = self._engine("popoto_tombstone_prior")
        stats = self._engine("popoto_tombstone_stats")
        rows, _ = self._run(
            f"WITH d AS (DELETE FROM {prior} WHERE model = %s RETURNING 1), "
            f"s AS (DELETE FROM {stats} WHERE model = %s) SELECT count(*) FROM d",
            [spec.name, spec.name],
            uow=uow,
            write=True,
        )
        return int(rows[0][0])

    # -- reconciliation's embedding cache ---------------------------------------------

    def _embed_cache_get(
        self, spec: ModelSpec, member: str, *, uow: Optional[UnitOfWork] = None
    ) -> Optional[list[float]]:
        """``HGET POPOTO:M5:embedding_cache <member>``: the cached vector."""
        table = self._engine("popoto_embedding_cache")
        rows, _ = self._run(
            f"SELECT vector FROM {table} WHERE model = %s AND member = %s",
            [spec.name, member],
            uow=uow,
        )
        return [float(v) for v in rows[0][0]] if rows else None

    def _embed_cache_set(
        self,
        spec: ModelSpec,
        member: str,
        vector: Sequence[float],
        *,
        uow: Optional[UnitOfWork] = None,
    ) -> None:
        from psycopg.types.json import Jsonb

        table = self._engine("popoto_embedding_cache")
        self._run(
            f"INSERT INTO {table} (model, member, vector) VALUES (%s, %s, %s) "
            "ON CONFLICT (model, member) DO UPDATE SET vector = EXCLUDED.vector",
            [spec.name, member, Jsonb([float(v) for v in vector])],
            uow=uow,
            write=True,
        )

    def _embed_cache_drop(
        self, spec: ModelSpec, member: str, *, uow: Optional[UnitOfWork] = None
    ) -> int:
        table = self._engine("popoto_embedding_cache")
        _, count = self._run(
            f"DELETE FROM {table} WHERE model = %s AND member = %s",
            [spec.name, member],
            uow=uow,
            write=True,
        )
        return int(count or 0)

    # -- NeverRecordMixin's audit log -----------------------------------------------

    def _nr_drop(
        self,
        spec: ModelSpec,
        reason: str,
        entry: str,
        keep: int,
        *,
        uow: Optional[UnitOfWork] = None,
    ) -> None:
        """``HINCRBY counts <reason> 1``, ``LPUSH drops <entry>``, ``LTRIM``
        to the newest ``keep``: one message. The entry is the same
        content-free JSON the Redis list holds.

        A database error :meth:`_run` leaves unclassified (an ``UndefinedTable``
        after the audit tables were dropped under a warm memo, a permission
        error) is raised as :class:`~popoto.backends.BackendError`, never as
        raw psycopg (PR #793 review): the refused save's caller sees popoto's
        error family whether or not a unit of work carried the tombstone."""
        import psycopg

        from ..types import BackendError

        try:
            counts = self._engine("popoto_never_record_count")
            log = self._engine("popoto_never_record_log")
            self._run(
                f"INSERT INTO {counts} AS c (model, reason, count) VALUES (%s, %s, 1) "
                "ON CONFLICT (model, reason) DO UPDATE SET count = c.count + 1; "
                f"INSERT INTO {log} (model, entry) VALUES (%s, %s); "
                f"DELETE FROM {log} WHERE model = %s AND seq NOT IN ("
                f"SELECT seq FROM {log} WHERE model = %s ORDER BY seq DESC LIMIT %s)",
                [spec.name, reason, spec.name, entry, spec.name, spec.name, int(keep)],
                uow=uow,
                write=True,
            )
        except psycopg.Error as exc:
            raise BackendError(
                f"popoto could not write the never-record tombstone for "
                f"{spec.name} (SQLSTATE {getattr(exc, 'sqlstate', None)}: "
                f"{type(exc).__name__}: {exc}); the save was refused regardless"
            ) from exc

    def _nr_counts(
        self, spec: ModelSpec, *, uow: Optional[UnitOfWork] = None
    ) -> dict[str, int]:
        counts = self._engine("popoto_never_record_count")
        rows, _ = self._run(
            f"SELECT reason, count FROM {counts} WHERE model = %s",
            [spec.name],
            uow=uow,
        )
        return {reason: int(count) for reason, count in rows}

    def _nr_log(
        self, spec: ModelSpec, limit: int, *, uow: Optional[UnitOfWork] = None
    ) -> list[str]:
        """``LRANGE drops 0 limit-1``: newest first, with ``LRANGE``'s
        negative stop (``limit=0`` is the whole log). The log is capped at
        ``Defaults.NR_TOMBSTONE_LOG_MAX`` rows, so it is read whole."""
        log = self._engine("popoto_never_record_log")
        rows, _ = self._run(
            f"SELECT entry FROM {log} WHERE model = %s ORDER BY seq DESC",
            [spec.name],
            uow=uow,
        )
        entries = [row[0] for row in rows]
        stop = int(limit) - 1
        if stop < 0:
            stop += len(entries)
        return entries[: max(stop + 1, 0)]

    # -- the question queue -------------------------------------------------------------

    def _qq_deliver(
        self,
        spec: ModelSpec,
        field: str,
        agent: str,
        keys: Sequence[str],
        turn: int,
        budget_turns: int,
        ttl_seconds: float,
        allowed: Sequence[str],
        *,
        uow: Optional[UnitOfWork] = None,
    ) -> Optional[tuple[int, int]]:
        """``_DELIVER_LUA`` (module docstring). Returns ``(index, ask_count)``
        (the 1-based index into ``keys``) on a delivery, else ``None``."""
        if not keys:
            return None
        ts = self._table(spec, write=True)
        bucket = self._engine("popoto_question_bucket")
        lock = f"popoto:qq:{quote_ident(self.schema)}:{agent}"
        sql = (
            "SELECT pg_advisory_xact_lock(hashtextextended(%s, 0)); "
            f"WITH b AS (SELECT last_turn FROM {bucket} WHERE agent = %s "
            f"AND expires_at > {_NOW}), "
            'pick AS (SELECT t."_pk", coalesce(t."ask_count", 0) + 1 AS n, k.ord '
            "FROM unnest(%s::text[]) WITH ORDINALITY AS k(pk, ord) "
            f'JOIN {ts.qualified} AS t ON t."_pk" = k.pk '
            "WHERE NOT EXISTS (SELECT 1 FROM b WHERE %s < b.last_turn + %s) "
            'AND t."status" = ANY(%s::text[]) '
            'AND (t."cooldown_until" IS NULL OR NOT (%s < t."cooldown_until")) '
            "ORDER BY k.ord LIMIT 1 FOR UPDATE OF t SKIP LOCKED), "
            f"upd AS (UPDATE {ts.qualified} AS t SET \"status\" = 'delivered', "
            '"ask_count" = pick.n, "delivered_turn" = %s, "_updated_at" = now(), '
            '"_migrated_from" = NULL FROM pick WHERE t."_pk" = pick."_pk" '
            "RETURNING pick.ord, pick.n), "
            f"bk AS (INSERT INTO {bucket} AS q (agent, last_turn, expires_at) "
            f"SELECT %s, %s, {_NOW} + %s FROM upd "
            "ON CONFLICT (agent) DO UPDATE SET last_turn = EXCLUDED.last_turn, "
            "expires_at = EXCLUDED.expires_at) "
            "SELECT ord, n FROM upd"
        )
        params = [
            lock,
            agent,
            list(keys),
            int(turn),
            int(budget_turns),
            list(allowed),
            int(turn),
            int(turn),
            agent,
            int(turn),
            float(ttl_seconds),
        ]
        rows, _ = self._run(sql, params, uow=uow, write=True)
        if not rows:
            return None
        return int(rows[0][0]), int(rows[0][1])

    def _qq_claim(
        self,
        spec: ModelSpec,
        field: str,
        id: RecordId,
        allowed: Sequence[str],
        updates: Mapping[str, Any],
        guard: Mapping[str, Any],
        *,
        uow: Optional[UnitOfWork] = None,
    ) -> bool:
        """``_CLAIM_LUA``: compare-and-set on ``status`` (and the guard
        fields, an absent value comparing as ``NULL``), then the updates.
        A record writer: its key lock first, then the row."""
        from .plan import to_column_value

        ts = self._table(spec, write=True)
        sets = []
        params: list[Any] = []
        for name, value in updates.items():
            sets.append(f"{quote_ident(name)} = %s")
            params.append(to_column_value(ts, name, value))
        sets.append('"_updated_at" = now(), "_migrated_from" = NULL')
        conds = ['"_pk" = %s', '"status" = ANY(%s::text[])']
        params += [id.canonical, list(allowed)]
        for name, value in guard.items():
            conds.append(f"{quote_ident(name)} IS NOT DISTINCT FROM %s")
            params.append(to_column_value(ts, name, value))
        sql, params = self._record_locked(
            ts,
            [id.canonical],
            f"UPDATE {ts.qualified} SET {', '.join(sets)} "
            f"WHERE {' AND '.join(conds)} RETURNING 1",
            params,
        )
        rows, _ = self._run(sql, params, uow=uow, write=True)
        return bool(rows)

    def _lease_lock(
        self,
        spec: ModelSpec,
        field: str,
        key: str,
        token: str,
        ttl_ms: int,
        *,
        uow: Optional[UnitOfWork] = None,
    ) -> bool:
        """``SET key token NX PX ttl``: an expired lease is absent. Serves the
        question queue's propose lock (``_qq``) and the decision log's
        assembly claim (``_lease``)."""
        table = self._engine("popoto_lease")
        rows, _ = self._run(
            f"INSERT INTO {table} AS l (key, token, expires_at) "
            f"VALUES (%s, %s, {_NOW} + %s) ON CONFLICT (key) DO UPDATE SET "
            "token = EXCLUDED.token, expires_at = EXCLUDED.expires_at "
            f"WHERE l.expires_at <= {_NOW} RETURNING 1",
            [key, token, float(ttl_ms) / 1000.0],
            uow=uow,
            write=True,
        )
        return bool(rows)

    def _lease_release(
        self,
        spec: ModelSpec,
        field: str,
        key: str,
        token: str,
        *,
        uow: Optional[UnitOfWork] = None,
    ) -> int:
        """``_RELEASE_LUA`` / ``CLAIM_RELEASE_LUA``: delete the lease only
        while this token owns it."""
        table = self._engine("popoto_lease")
        _, count = self._run(
            f"DELETE FROM {table} WHERE key = %s AND token = %s",
            [key, token],
            uow=uow,
            write=True,
        )
        return int(count or 0)

    # -- the decision log (#811) -----------------------------------------------------

    def _m3_terminal_write(
        self,
        spec: ModelSpec,
        field: str,
        record: Any,
        refused_detail: str,
        *,
        uow: Optional[UnitOfWork] = None,
    ) -> bool:
        """``TERMINAL_WRITE_LUA``'s guarded write as one statement.

        ``INSERT ... ON CONFLICT (_pk) DO UPDATE ... WHERE NOT (state =
        'accept' AND entry_id <> '')`` writes a new row, or rewrites an
        existing one unless it is an assembled accept. When that guard is
        false the row is locked but not updated and ``RETURNING`` yields
        nothing; only then does the second branch record ``refused_detail``
        on the standing row. The branches are mutually exclusive, so the row
        is modified at most once per statement. Returns ``True`` when the row
        was written, ``False`` when refused. The record-key advisory lock
        serialises it with ORM saves of the same row (``write_pending``).
        Replaces the Redis class-set and index-set bookkeeping, which the
        table's own indexes cover."""
        ts = self._table(spec, write=True)
        names = [n for n in spec.fields if n in ts.field_types]
        values = self._row_values(ts, record, names)
        pk = record.db_key.redis_key
        cols = ["_pk"] + list(values)
        col_sql = ", ".join(quote_ident(c) for c in cols)
        slots = ", ".join(["%s"] * len(cols))
        updates = ", ".join(
            f"{quote_ident(c)} = EXCLUDED.{quote_ident(c)}"
            for c in cols[1:]
            if c not in ts.key_fields
        )
        updates += ', "_updated_at" = now(), "_migrated_from" = NULL'
        guard = "NOT (t.\"state\" = 'accept' AND coalesce(t.\"entry_id\", '') <> '')"
        sql = (
            f"WITH up AS (INSERT INTO {ts.qualified} AS t ({col_sql}) "
            f'VALUES ({slots}) ON CONFLICT ("_pk") DO UPDATE SET {updates} '
            f"WHERE {guard} RETURNING 1), "
            f'refuse AS (UPDATE {ts.qualified} SET "detail_code" = %s '
            'WHERE "_pk" = %s AND NOT EXISTS (SELECT 1 FROM up) RETURNING 1) '
            "SELECT (SELECT count(*) FROM up), (SELECT count(*) FROM refuse)"
        )
        params = [pk] + list(values.values()) + [refused_detail, pk]
        sql, params = self._record_locked(ts, [pk], sql, params)
        rows, _ = self._run(sql, params, uow=uow, write=True)
        self._after_write(ts, uow)
        return bool(rows) and int(rows[0][0]) > 0

    def _m3_turn_summary(
        self,
        spec: ModelSpec,
        field: str,
        agent_id: str,
        turn_id: str,
        states: Sequence[str],
        *,
        uow: Optional[UnitOfWork] = None,
    ) -> list[tuple[str, Optional[str], int]]:
        """The per-turn summary hash as an aggregate over the detail rows:
        ``(state, reason_code, count)`` for the turn's rows whose current
        state is one of ``states``. One snapshot-consistent read, as
        ``HGETALL`` is on Redis; derived, so it cannot drift."""
        ts = self._table(spec)
        rows, _ = self._run(
            f'SELECT "state", "reason_code", count(*) FROM {ts.qualified} '
            'WHERE "agent_id" = %s AND "turn_id" = %s AND "state" = ANY(%s::text[]) '
            'GROUP BY "state", "reason_code"',
            [agent_id, turn_id, list(states)],
            uow=uow,
        )
        return [(str(r[0]), r[1], int(r[2])) for r in rows]

    # -- the harness integration's session state (#814) ------------------------------

    @staticmethod
    def _harness_session_lock(kind: str) -> str:
        """The advisory lock that serialises one session's writes to one
        harness table (parameters: schema, agent, session). Spelled as a
        concatenation so ``record_lock_keys``, which reads statement heads,
        never mistakes it for a record-key lock."""
        return (
            "SELECT pg_advisory_xact_lock(hashtextextended("
            f"'popoto:harness:{kind}:' || %s || ':' || %s || ':' || %s, 0)); "
        )

    @staticmethod
    def _harness_reap(table: str) -> str:
        """Delete a bounded batch of expired rows (any session), in passing."""
        return (
            f"DELETE FROM {table} WHERE ctid = ANY(ARRAY(SELECT ctid FROM {table} "
            f"WHERE expires_at <= {_NOW} LIMIT {HARNESS_REAP_BATCH} "
            "FOR UPDATE SKIP LOCKED)); "
        )

    def _harness_pending_push(
        self,
        spec: ModelSpec,
        agent: str,
        session: str,
        keys: Sequence[str],
        turn: Optional[str],
        cap: int,
        ttl: float,
        *,
        uow: Optional[UnitOfWork] = None,
    ) -> None:
        """``RPUSH`` + ``LTRIM -cap -1`` + ``EXPIRE`` in one message, under
        the session's advisory lock. With a ``turn``, the entry is staged only
        when no live entry carries that turn yet -- the ``LRANGE`` check
        Redis makes before its pipeline, exact here because it runs under the
        lock. Every live entry's expiry is refreshed, as ``EXPIRE`` refreshes
        the list, and everything past the newest ``cap`` is dropped."""
        table = self._engine("popoto_harness_pending")
        live = f"agent = %s AND session = %s AND expires_at > {_NOW}"
        self._run(
            self._harness_session_lock("pending")
            + self._harness_reap(table)
            + f"INSERT INTO {table} (agent, session, turn, keys, expires_at) "
            f"SELECT %s, %s, %s::text, %s::text[], {_NOW} + %s "
            f"WHERE %s::text IS NULL OR NOT EXISTS (SELECT 1 FROM {table} "
            f"WHERE {live} AND turn = %s::text); "
            f"UPDATE {table} SET expires_at = {_NOW} + %s WHERE {live}; "
            f"DELETE FROM {table} WHERE agent = %s AND session = %s AND seq "
            f"NOT IN (SELECT seq FROM {table} WHERE {live} "
            "ORDER BY seq DESC LIMIT %s)",
            [
                self.schema,
                agent,
                session,
                # INSERT
                agent,
                session,
                turn,
                list(keys),
                float(ttl),
                turn,
                agent,
                session,
                turn,
                # UPDATE
                float(ttl),
                agent,
                session,
                # DELETE (the cap)
                agent,
                session,
                agent,
                session,
                int(cap),
            ],
            uow=uow,
            write=True,
        )

    def _harness_pending_claim(
        self,
        spec: ModelSpec,
        agent: str,
        session: str,
        turn: str,
        *,
        uow: Optional[UnitOfWork] = None,
    ) -> tuple[Optional[list[str]], bool, bool]:
        """Claim the oldest live entry staged for ``turn``: ``(keys, hit,
        saw_tagged)``. ``keys`` is ``None`` unless *this* call deleted the
        entry, so of two callers racing on one turn exactly one gets it -- the
        ``LRANGE`` + ``LREM`` claim in one statement. ``hit`` says an entry
        for the turn existed; ``saw_tagged`` that some live entry of the
        session carries a turn at all, which decides between a miss and the
        positional fallback. Under the session's lock, as the push is, so a
        push's expiry refresh (which row-locks every live entry) is never
        seen half-done."""
        table = self._engine("popoto_harness_pending")
        rows, _ = self._run(
            self._harness_session_lock("pending")
            + f"WITH live AS (SELECT seq, turn FROM {table} WHERE agent = %s "
            f"AND session = %s AND expires_at > {_NOW}), "
            "hit AS (SELECT seq FROM live WHERE turn = %s ORDER BY seq LIMIT 1), "
            f"del AS (DELETE FROM {table} WHERE agent = %s AND session = %s "
            "AND seq IN (SELECT seq FROM hit) RETURNING keys) "
            "SELECT (SELECT keys FROM del), EXISTS (SELECT 1 FROM hit), "
            "EXISTS (SELECT 1 FROM live WHERE turn IS NOT NULL)",
            [self.schema, agent, session, agent, session, turn, agent, session],
            uow=uow,
            write=True,
        )
        keys, hit, saw_tagged = rows[0]
        return (
            None if keys is None else [str(k) for k in keys],
            bool(hit),
            bool(saw_tagged),
        )

    def _harness_pending_pop(
        self,
        spec: ModelSpec,
        agent: str,
        session: str,
        *,
        uow: Optional[UnitOfWork] = None,
    ) -> Optional[list[str]]:
        """``LPOP``: delete the oldest live entry and return its keys, or
        ``None``.

        Under the session's advisory lock, which serialises it with the push
        and with other pops, as Redis serialises ``LPOP`` with the push
        pipeline. It must not ``SKIP LOCKED`` instead: the push's expiry
        refresh row-locks every live entry, so a skipping pop that ran
        alongside it found nothing, left turn N's entry behind, and the next
        pop paired it with turn N+1's outcome (the #574 misattribution). Two
        concurrent pops still take two entries: the second runs after the
        first commits and, in a fresh statement snapshot, sees the next one."""
        table = self._engine("popoto_harness_pending")
        rows, _ = self._run(
            self._harness_session_lock("pending")
            + f"DELETE FROM {table} WHERE agent = %s AND session = %s AND seq = ("
            f"SELECT seq FROM {table} WHERE agent = %s AND session = %s "
            f"AND expires_at > {_NOW} ORDER BY seq LIMIT 1 FOR UPDATE) "
            "RETURNING keys",
            [self.schema, agent, session, agent, session, agent, session],
            uow=uow,
            write=True,
        )
        return [str(k) for k in rows[0][0]] if rows else None

    def _harness_injected_read(
        self,
        spec: ModelSpec,
        agent: str,
        session: str,
        *,
        uow: Optional[UnitOfWork] = None,
    ) -> list[str]:
        """``SMEMBERS``: the session's live injected record keys."""
        table = self._engine("popoto_harness_injected")
        rows, _ = self._run(
            f"SELECT member FROM {table} WHERE agent = %s AND session = %s "
            f"AND expires_at > {_NOW}",
            [agent, session],
            uow=uow,
        )
        return [str(row[0]) for row in rows]

    def _harness_injected_mark(
        self,
        spec: ModelSpec,
        agent: str,
        session: str,
        members: Sequence[str],
        ttl: float,
        *,
        uow: Optional[UnitOfWork] = None,
    ) -> None:
        """``SADD`` + ``EXPIRE`` in one message, under the session's lock. A
        set whose expiry has passed is gone before the add, as an expired
        Redis key is, so a member injected over an hour ago does not come back
        alive with the next turn's."""
        table = self._engine("popoto_harness_injected")
        of_session = "agent = %s AND session = %s"
        self._run(
            self._harness_session_lock("injected")
            + self._harness_reap(table)
            + f"DELETE FROM {table} WHERE {of_session} AND expires_at <= {_NOW}; "
            f"UPDATE {table} SET expires_at = {_NOW} + %s WHERE {of_session}; "
            f"INSERT INTO {table} (agent, session, member, expires_at) "
            f"SELECT DISTINCT %s, %s, m, {_NOW} + %s FROM unnest(%s::text[]) AS m "
            "ON CONFLICT (agent, session, member) DO UPDATE "
            "SET expires_at = EXCLUDED.expires_at",
            [
                self.schema,
                agent,
                session,
                # DELETE (the expired set)
                agent,
                session,
                # UPDATE
                float(ttl),
                agent,
                session,
                # INSERT
                agent,
                session,
                float(ttl),
                list(members),
            ],
            uow=uow,
            write=True,
        )

    def _harness_touch(
        self,
        spec: ModelSpec,
        agent: str,
        name: str,
        stamp: str,
        counter_key: str,
        *,
        uow: Optional[UnitOfWork] = None,
    ) -> None:
        """The success probe: ``SET last:<name> <stamp>`` and ``INCR
        <counter_key>``, the Redis ``MULTI`` pair, as one statement."""
        events = self._engine("popoto_harness_event")
        counters = self._engine("popoto_counter")
        self._run(
            f"WITH e AS (INSERT INTO {events} (agent, name, stamp) "
            "VALUES (%s, %s, %s) ON CONFLICT (agent, name) DO UPDATE "
            "SET stamp = EXCLUDED.stamp) "
            f"INSERT INTO {counters} AS c (key, value) VALUES (%s, 1) "
            "ON CONFLICT (key) DO UPDATE SET value = c.value + 1",
            [agent, name, stamp, counter_key],
            uow=uow,
            write=True,
        )

    def _harness_events(
        self, spec: ModelSpec, agent: str, *, uow: Optional[UnitOfWork] = None
    ) -> dict[str, str]:
        """Every last-success timestamp recorded for ``agent``."""
        table = self._engine("popoto_harness_event")
        rows, _ = self._run(
            f"SELECT name, stamp FROM {table} WHERE agent = %s", [agent], uow=uow
        )
        return {str(name): str(stamp) for name, stamp in rows}

    def _harness_purge(
        self,
        spec: ModelSpec,
        agent: str,
        counter_prefix: str,
        *,
        uow: Optional[UnitOfWork] = None,
    ) -> int:
        """Delete everything the integration keeps for ``agent``: its pending
        handoff, injected sets, last-success stamps, and the counters whose
        key starts with ``counter_prefix`` -- the Postgres twin of the
        ``SCAN MATCH`` + ``DEL`` sweep over the agent's Redis keys. One
        message, so one implicit transaction. Returns the rows removed."""
        pending = self._engine("popoto_harness_pending")
        injected = self._engine("popoto_harness_injected")
        events = self._engine("popoto_harness_event")
        counters = self._engine("popoto_counter")
        rows, _ = self._run(
            f"WITH p AS (DELETE FROM {pending} WHERE agent = %s RETURNING 1), "
            f"i AS (DELETE FROM {injected} WHERE agent = %s RETURNING 1), "
            f"e AS (DELETE FROM {events} WHERE agent = %s RETURNING 1), "
            f"c AS (DELETE FROM {counters} WHERE starts_with(key, %s) RETURNING 1) "
            "SELECT (SELECT count(*) FROM p) + (SELECT count(*) FROM i) "
            "+ (SELECT count(*) FROM e) + (SELECT count(*) FROM c)",
            [agent, agent, agent, counter_prefix],
            uow=uow,
            write=True,
        )
        return int(rows[0][0]) if rows else 0