Quickstart: Command the Data Layer

The transparent wrapper exposes a consistent API. Tenant isolation, soft-delete, timestamps, and audit logging happen automatically.

```typescript // Inside any Aeion route handler, MCP tool, or service const { docs, hasMore, cursor } = await ctx.db.find("contacts", { where: { score: { gt: 80 } }, sort: "-lastActivityAt", limit: 10, });

// Lookup by ID const contact = await ctx.db.findById("contacts", "ct_xyz");

// findOne takes a where-filter, not an ID const contactByEmail = await ctx.db.findOne("contacts", { email: "jane@example.com", });

const newContact = await ctx.db.create("contacts", { email: "jane@example.com", firstName: "Jane", });

await ctx.db.update("contacts", "ct_xyz", { status: "active" }); await ctx.db.delete("contacts", "ct_xyz"); ```

What happens automatically:

• tenantId = ctx.tenant.id injected into every query
• RBAC filter applied (only return authorized records)
• Field-level access checks (sensitive fields stripped)
• Soft-delete filter (only return non-deleted by default)
• Audit log entry created
• Temporal event emitted (for replay / time-travel)

Operators (programmatic API — full zFilter set, 30+ operators): comparison (equals, not_equals, gt, gte, lt, lte, between, not_between), string (contains, not_contains, starts_with, ends_with, matches, ilike, search), array (in, not_in, contains_any, overlaps, has_any, has_all), null (is_null, is_not_null, exists), JSON (json_contains, json_path_equals, has_key, has_keys), date (before, after, older_than, newer_than), relational (some, every, none, count), and logical groupings (AND, OR, NOT).

For complex aggregations, joins, or raw SQL, use the same proxy — it routes directly to Drizzle.

typescript // Complex aggregation const stats = await ctx.db .select({ region: schema.crm_contacts.region, count: sql<number>count(*)::int, avgScore: sql<number>avg(${schema.crm_contacts.score})`, }) .from(schema.crm_contacts) .groupBy(schema.crm_contacts.region);

// Join const dealsWithContacts = await ctx.db .select() .from(schema.crm_deals) .leftJoin( schema.crm_contacts, eq(schema.crm_deals.contactId, schema.crm_contacts.id), ) .where(eq(schema.crm_deals.stage, "active"));

// Raw SQL (parameterized) const result = await ctx.db.execute(sql SELECT COUNT(*) FROM ${schema.crm_contacts} WHERE created_at > NOW() - INTERVAL '30 days' ); ```

Multi-tenant safety preserved — even in raw Drizzle, the wrapper enforces tenant isolation. Cross-tenant queries from a request context return an explicit error.

Type-safe end-to-end via Drizzle's schema types.

Define security on your collection schema:

```typescript import { createAccessControl, createScopedReadAccess, hasAnyRole, } from "@aeion/core/schema/security/accessControlHelpers"; import type { CollectionConfig } from "@aeion/types/schema";

export const HighSecurityAssets: CollectionConfig = { slug: "secure_assets", access: createAccessControl({ // STAGE 1 — Pre-Write Gate create: ["admin"], update: ["admin", "asset-manager"], delete: ["admin"],

// STAGE 2 — Pre-Query Gate (Row-Level Security) read: createScopedReadAccess(async (ctx, user) => { if (hasAnyRole(user, ["admin"])) return true; return { ownerId: { equals: user.id } }; }), }), fields: [ { name: "title", type: "text" }, { name: "ownerId", type: "relationship", relationTo: "users" }, { name: "financialValuation", type: "number", access: { // STAGE 3 — Post-Read Masking read: ({ user }) => hasAnyRole(user, ["admin", "finance-manager"]), }, }, ], }; ```

3-stage enforcement on every API call:

1. Pre-Write: mutations rejected if user lacks permission
2. Pre-Query (RLS): every read has user's filter injected before SQL
3. Post-Read: sensitive field values stripped from response payload

Defense in depth — even if one stage is bypassed, others catch the attempt.

Every mutation captured via temporal events. Replay any past state.

```typescript import { reconstructAtTime, getDocumentHistory, getDocumentTimeline, compareAtTimes, } from "@aeion/core/temporal";

// Get the event-by-event history of a document const history = await getDocumentHistory({ ctx, collection: "pages", id: "page_123", });

// Reconstruct the document as it existed at a specific moment const pageYesterday = await reconstructAtTime({ ctx, collection: "pages", id: "page_123", asOf: "2026-05-19T18:00:00Z", });

// Compare two points in time const diff = await compareAtTimes({ ctx, collection: "pages", id: "page_123", fromTime: "2026-05-19T00:00:00Z", toTime: "2026-05-20T00:00:00Z", });

// Restoring a document to a past state is a write — pass the reconstructed // state to ctx.db.update(). The temporal layer captures the restore as a // new event so the original timeline stays auditable. await ctx.db.update("pages", "page_123", pageYesterday.doc); ```

Use cases:

• "I accidentally overwrote..." — UX rescue
• Debugging — "What did this look like 2 hours ago?"
• Compliance / forensic — "What did the user see at dispute time?"
• Replay testing — replay 1 day of mutations against staging

Storage — RFC 6902 JSON Patches (compact). Typical overhead: 2-5% of base table size. Retention configurable per collection.

Aegis integration — temporal events feed cross-collection rollback. "Restore my tenant to last Tuesday" works because every mutation is replayable.

Aegis intercepts dangerous database operations:

Protected against:

• DROP TABLE / TRUNCATE / DELETE on tables with real data
• ALTER TABLE that destroys columns
• UPDATE WHERE with no proper filter

Pre-flight check on `bun run db:sync`:

```bash $ bun run db:sync

🚨 Aegis Guardrail: This migration would DROP table crm_contacts (currently has 247,891 rows) To proceed, run with --force-destructive flag. Aborting. ```

Force-destructive mode:

```bash $ bun run db:sync --force-destructive

🚨 Aegis Guardrail: Creating safety snapshot before destructive migration... ✓ Snapshot created: aegis_snapshots/2026-05-20T15-30-00.sql.gz (24 MB) ✓ Proceeding with migration... ✓ Migration complete. Snapshot retained for 90 days. ```

Rollback any migration via Admin → Aegis → Rollback Migration. Pre-migration snapshots retained for 90 days.

Run-anywhere safety — same checks in dev / staging / production. No surprise behavior.

Every data access automatically logged.

Default fields captured:

• User identity, tenant ID, operation type
• Collection + record ID
• Field-level details (which fields read / changed)
• IP, device fingerprint, HTTP method, endpoint
• Latency, result size, outcome

Compliance tagging:

typescript export const PaymentMethods: CollectionConfig = { slug: "payment_methods", governance: { auditLevel: "high", complianceFrameworks: ["pci", "gdpr"], retentionDays: 365, }, };

Query the audit log — it's a regular collection (slug audit_log), queried via the standard service registry:

```typescript // "Who accessed customer ct_xyz in the last 24 hours?" const entries = await ctx.services["audit_log"].list({ ctx, where: { resourceCollection: { equals: "contacts" }, resourceId: { equals: "ct_xyz" }, createdAt: { newer_than: "24h" }, }, limit: 100, });

// "Show all data exports by user u_admin in the last 30 days" const exports = await ctx.services["audit_log"].list({ ctx, where: { actorId: { equals: "u_admin" }, action: { equals: "export" }, createdAt: { newer_than: "30d" }, }, }); ```

SIEM integration — push to Splunk / DataDog / Sumo Logic / Elastic via streaming audit-log connector.