qbit-record-files/AGENTS.md

AGENTS.md

Guidance for agents working in this repository.

Project Overview

QBit Record Files: retained, ordered, reviewed and audited files for QQQ records, on top of the standard qbit-collaboration attachment path. Status and limits: docs/TODO.md, docs/V1-REMAINING.md.

Build Commands

This qbit needs a published qbit-collaboration that contains the attachment lifecycle SPI (qbit-collaboration.version in pom.xml). Use the wrapper (Maven 3.10 cannot read the parent POM):

./mvnw verify

Invariants

• Entry point: RecordFilesQBitProducer. It refuses to install unless collaboration is produced first with RecordFilesAttachmentLifecycle as its attachment lifecycle.
• Collaboration never imports this qbit; this qbit imports only the contracts listed in DependencyBoundaryTest. No scripting, generation or printing dependency.
• Never write collaboration tables and never duplicate file bytes: upload through AttachmentsService.
• RecordFilesStore is the only reader/writer of Record Files tables and has no delete. Direct user writes to file, collection, item and event are denied by the permission checker; services use an explicit, reasoned permission bypass after their own checks.
• Every service re-checks its permission and that the caller can see the source record. Missing and invisible look the same (QNotFoundException("Not found")).
• Audit is strict: a durable independent attempt first (fail closed), then the change and its outcome event together. Never add a DOWNLOADED/PRINTED event without a real observation.
• Retained originals are immutable: services change only lifecycle, category, review fields. Rejecting a file never deletes it.

Naming (owner rule, same as collaboration)

• Tables: lowercase snake_case with the full qbit prefix record_files_<name>; QQQ and SQL names are identical. Permissions: record-files.<action>.
• Qbit data lives in standard, visible QQQ tables secured by permissions and parent visibility, never hidden.

Code Style

Same as collaboration: 3-space indentation, braces on the next line, return (x);, flower-box Javadoc on every class and method, fluent withX() setters, wrapper types in config and entities. Checkstyle config is copied from collaboration and fails the build.

Dependencies

Java 21. Parent com.kingsrook:qbit-build-parent:2.1.1; the qqq-snapshot profile imports qqq-bom-pom:4.1.0-RC.15 exactly as collaboration does. Tests: JUnit 5, AssertJ.