0 Fork 0

Files

T

refactor(backups): core TableSchemaFingerprint and KeysetPager (QQQ 4.1.0-RC.6)

Replace the RC.6 stand-ins in TableFingerprints, TableReader and
StandardRestoreWriter with core TableSchemaFingerprint and KeysetPager.

Core fingerprints differ from the local ones: descriptor names, unique
keys as lists, association joinName, and empty-string backend types. New
manifests therefore record fingerprintAlgorithm "qqq-table-schema-v1".
A manifest without the field uses the frozen LegacyTableFingerprint, so
old backups still verify and restore.

Paging keeps ascending primary-key order, exclusive resume cursors,
bounded pages and the caller's transaction. Restore writes now require
the explicit backups.restore permission, checked during Review.

Closes #19 (architecture review QRun-IO/qqq#1150, finding F3).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

2026-10-13 20:36:44 -05:00

2.0 KiB

Raw Permalink Blame History

AGENTS.md

This file provides guidance to Codex when working with code in this repository.

Project Overview

QBit Backups: QQQ QBit: logical backup, restore and verification of QQQ data to S3-compatible storage. Design: QRun-IO/qqq#1091. Implementation in progress.

Build Commands

./mvnw compile          # Compile (always use the wrapper: Maven 3.10 cannot read the parent POM)
./mvnw test             # Unit tests
./mvnw verify           # Unit tests + JaCoCo gate (70% instructions, 90% classes)

Architecture

Entry point: BackupsQBitProducer implements QBitMetaDataProducer<BackupsQBitConfig> in com.kingsrook.qbits.backups. Component producers in this package (and below) are found by package scanning.

Naming (owner rule)

Tables are lowercase snake_case prefixed with the full qbit name: backups_<name>. The QQQ table name and the backend (SQL) name are identical; possible-value sources take the table name.
Permissions use the full qbit name: backups.<action> (for example backups.view, backups.admin).
Qbit data lives in standard, visible QQQ tables, secured by permissions and record security locks, never hidden.
Processes run as table or record actions, never in the nav.

Code Style

3-space indentation, opening braces on the next line, return (x);.
Javadoc flower-box comments (/***** with ** lines) on every class and method.
Fluent setters (withX()).
Wrapper types (Integer, Boolean) in config and entities.

Dependencies

Java 21.
Parent com.kingsrook:qbit-build-parent:2.0.0 (qqq 4.0.0). The default-active qqq-snapshot profile imports qqq-bom-pom:4.1.0-RC.6 ahead of it, as in qbit-quick-search (ADR-0007). Remove that activation when the parent moves to 4.1.
Tests: JUnit 5, AssertJ.

Release

CircleCI qqq-orb 0.6.8.
develop publishes SNAPSHOTs.
A release/* branch publishes RCs (the orb bumps the version).
A v* tag publishes the release.

2.0 KiB Raw Permalink Blame History