DAL

AI Agent Rules and Skills

Relevant source files

The following files were used as context for generating this wiki page:

This page documents the configuration, guardrails, and specialized skills defined for AI agents (specifically Devin) interacting with the @primebrick/dal-pg codebase. These rules ensure architectural consistency, maintain the "leaf dependency" status of the DAL, and enforce the "snake_case everywhere" design principle.

Devin Agent Configuration

The agent behavior is governed by a set of "always-on" rules located in .devin/rules/. These rules take precedence over general LLM patterns and are designed to prevent common errors like truncated filenames or architectural leakage.

Mandatory Operational Rules

Always Check Rules First: Before any write operation, file creation, or terminal command, the agent must read the .devin/rules/ directory and AGENTS.md to identify applicable constraints .devin/rules/always-check-rules-first.md:4-17.
Never Commit Automatically: Agents are strictly forbidden from executing git commit without explicit human instruction AGENTS.md:3-9.
File Creation Verification: To combat a known streaming bug where filenames are truncated, agents must verify the exact filename after a write call and delete any partial "sibling" files (e.g., if package is created alongside package.json) .devin/rules/verify-file-creation.md:1-30.
Temporary File Hygiene: Agents must never create temporary scripts or patches within the project repositories. They must use system temp directories (e.g., /tmp/) and clean them up immediately after use .devin/rules/temp-files.md:5-26.

Code Guardrails

The agent follows a "Halt on Failure" policy to prevent hallucinated fixes during development:

Self-Correction Limit: Maximum of 2 attempts to fix a linter or test failure .devin/rules/code-guardrails.md:6-7.
Escalation: If the error persists after the 2nd attempt, the agent must stop, set its state to BLOCKED, and wait for user guidance .devin/rules/code-guardrails.md:8-10.
Scope Locking: Agents cannot alter function signatures or shared structures unless explicitly authorized in a pre-approved plan .devin/rules/code-guardrails.md:12-15.

Sources: .devin/rules/always-check-rules-first.md:1-27, .devin/rules/code-guardrails.md:1-15, .devin/rules/temp-files.md:1-38, .devin/rules/verify-file-creation.md:1-66, AGENTS.md:1-10.

DAL Conventions and Guardrails

The following conventions are enforced by the agent to maintain the integrity of the Data Access Layer.

Dependency and Naming

Leaf Dependency: The DAL must never import from primebrick-be-v3 or primebrick-us-v3. It only depends on pg, pg-query-stream, and reflect-metadata .devin/rules/dal-conventions.md:3-11.
Snake_case Everywhere: This is a "Golden Rule." Database columns, TypeScript properties, and JSON keys must all remain snake_case. No DTO transformation or camelCase renaming is permitted .devin/rules/data-model-conventions.md:12-16.

Implementation Guardrails

Feature	Rule	Source
Write Returns	Always use `RETURNING *` for all inserts, updates, and deletes.	.devin/rules/dal-conventions.md:24-26
Find Defaults	`throwIfNotFound` is `true` by default; `deletedRecords` is `EXCLUDED` by default.	.devin/rules/dal-conventions.md:28-36
Bulk Strategy	Use the TEMP TABLE strategy for `updateMany` and `upsertMany`.	.devin/rules/dal-conventions.md:39-44
Numeric Types	`bigint` must be handled via `INT8_OID` to return native `bigint`.	.devin/rules/dal-conventions.md:46-52
Audit	Audit is port-based and fire-and-forget; it must not block the main path.	.devin/rules/dal-conventions.md:55-60
Transactions	The DAL never commits automatically.	.devin/rules/dal-conventions.md:86-90

Data Model Flow (Natural Language to Code Entity)

The following diagram illustrates how the agent maps requirements (Natural Language) to the specific code entities defined in the DAL rules.

Diagram: Data Model Mapping

Code
graph TD
    subgraph "Natural Language Space"
        NL1["'Create a new user'"]
        NL2["'Get active records'"]
        NL3["'Update 1000 rows'"]
    end

    subgraph "Code Entity Space"
        CE1["Repository.add() with RETURNING *"]
        CE2["FindOptions { deletedRecords: 'EXCLUDED' }"]
        CE3["TEMP TABLE strategy in updateMany()"]
    end

    NL1 -->|"Rule: RETURNING *"| CE1
    NL2 -->|"Rule: Default Soft-Delete"| CE2
    NL3 -->|"Rule: Set-based Execution"| CE3

Sources: .devin/rules/dal-conventions.md:1-94, .devin/rules/data-model-conventions.md:1-47.

Testing Rules

AI agents must verify all changes using the existing Vitest suite. Mocking the database is strictly forbidden.

Real PostgreSQL Required: Tests must run against a real database instance .devin/rules/dal-testing.md:5-9.
Idempotent Setup: Tables must be created via CREATE TABLE IF NOT EXISTS .devin/rules/dal-testing.md:18-19.
Isolation: Tables must be cleared between tests using TRUNCATE RESTART IDENTITY CASCADE .devin/rules/dal-testing.md:21-28.
Type Matrix: Every new type mapping must be added to TypeTestEntity to ensure round-trip fidelity .devin/rules/dal-testing.md:44-57.

Sources: .devin/rules/dal-testing.md:1-71.

Invokable Skills

The repository defines specialized skills that the agent can invoke to perform complex tasks.

dal-usage Skill

This skill provides the agent with a complete reference for bootstrapping and using the DAL gateway.

Bootstrap: Uses getDal() to create a singleton that manages the pg.Pool .devin/skills/dal-usage/SKILL.md:34-46.
Entity Definition: Enforces the use of decorators like @Entity, @Key, and @AuditableField .devin/skills/dal-usage/SKILL.md:54-78.
Timeout Management: Documents the use of statement_timeout (default 30s) as an anti-throttling measure .devin/skills/dal-usage/SKILL.md:30-31.
Manual Transactions: Uses withClient(fn, { timeoutMs }) for explicit transaction control .devin/skills/dal-usage/SKILL.md:144-161.

feature Skill

A high-level skill for end-to-end implementation:

Implement the feature.
Write Vitest tests using SimpleTestEntity or TypeTestEntity.
Run tests and fix failures (within the 2-attempt guardrail).
Summarize changes .devin/skills/feature/SKILL.md:1-10.

Skill Invocation Flow

This diagram shows how the agent transitions from a high-level task to specific DAL skill implementations.

Diagram: Skill Invocation Logic

Code
graph LR
    subgraph "Agent Task"
        Task["'Implement bulk upsert'"]
    end

    subgraph "Skill: dal-usage"
        S1["getDal() Singleton"]
        S2["upsertMany() with timeoutMs"]
        S3["Repository Class"]
    end

    subgraph "Code Implementation"
        CI1["src/dal/index.ts"]
        CI2["src/repository/Repository.ts"]
    end

    Task -->|"Invokes"| S2
    S2 -->|"Uses"| S1
    S1 -->|"Defined in"| CI1
    S2 -->|"Implemented in"| CI2

Sources: .devin/skills/dal-usage/SKILL.md:1-176, .devin/skills/feature/SKILL.md:1-10.

Last modified on July 13, 2026

Audit and Soft-Delete Subsystems

DAL