Core API

  Backend (gencow/ folder)              Frontend (src/ folder)
  ─────────────────────────         ─────────────────────────
  Runs on the server                Runs in the browser
  ┌──────────────────────┐         ┌──────────────────────┐
  │ gencow/schema.ts     │         │                      │
  │   → pgTable + ownerRls│         │ useQuery(api.tasks.  │
  │                       │         │   list)               │
  │ gencow/tasks.ts      │  WebSocket │   → { data, total } │
  │   → createCrud(tasks)│ ←──────→│                      │
  │   → procedure.query  │  Auto-   │ useMutation(api.tasks│
  │   → procedure.mutation│ Sync    │   .create)           │
  └──────────────────────┘         └──────────────────────┘

import { pgTable, serial, text, integer } from "drizzle-orm/pg-core";
import { ownerRls } from "@gencow/core";

// Apply RLS to the table — pass the userId column reference
export const tasks = pgTable("tasks", {
    id: serial("id").primaryKey(),
    title: text("title").notNull(),
    userId: text("user_id").notNull(),
}, (t) => ownerRls(t.userId));

// Public read — anyone can read, only owner can CUD
export const posts = pgTable("posts", {
    id: serial("id").primaryKey(),
    content: text("content").notNull(),
    userId: text("user_id").notNull(),
}, (t) => ownerRls(t.userId, { read: "public" }));

import { createCrud } from "./runtime";
import { tasks } from "./schema";

// Automatically registers: tasks.list, tasks.get, tasks.create, tasks.update, tasks.remove
export const { get, list, create, update, remove } = createCrud(tasks);

// ✅ Works — has id column
export const tasks = pgTable("tasks", {
    id: serial("id").primaryKey(),      // serial (number) PK
    title: text("title").notNull(),
});

// ✅ Also works — UUID string id
export const users = pgTable("users", {
    id: text("id").primaryKey(),         // text/UUID PK — auto-detected
    name: text("name"),
});

// ❌ Error — no id column
export const settings = pgTable("settings", {
    key: text("key").primaryKey(),       // createCrud() requires "id", not "key"
    value: text("value"),
});
// → [createCrud] Table "settings" must have an 'id' column.
// → Use manual procedure.query / procedure.mutation instead

// Backend: list returns { data: T[], total: number }
// Frontend:
const { data: result } = useQuery(api.tasks.list);

// ✅ Access data array
result?.data.map(task => <li>{task.title}</li>)

// ✅ Access total count (for pagination)
result?.total  // e.g. 42

// ❌ Common mistake — result is NOT an array
result?.map(...)  // TypeError! Use result.data.map() instead

const [page, setPage] = useState(1);
const limit = 20;
const { data: result } = useQuery(api.tasks.list, { page, limit });

const totalPages = Math.ceil((result?.total ?? 0) / limit);

return (
    <div>
        {result?.data.map(task => <TaskCard key={task.id} task={task} />)}
        <div>Page {page} of {totalPages} ({result?.total ?? 0} items)</div>
        <button onClick={() => setPage(p => p - 1)} disabled={page <= 1}>Prev</button>
        <button onClick={() => setPage(p => p + 1)} disabled={page >= totalPages}>Next</button>
    </div>
);

export const { list, get, create, update, remove } = createCrud(tasks, {
    // Auth
    allowAnonymous: true,      // Skip auth (default: false — Secure by Default)

    // Realtime
    realtime: false,           // Disable list and exact get invalidation (default: enabled)

    // Naming
    prefix: "myTasks",         // Override key prefix (default: table name)

    // Search — enables list({ search: "keyword" })
    searchFields: ["title", "description"],

    // Filtering — enables list({ filters: { status: "active" } })
    allowedFilters: ["status", "category"],

    // Pagination
    defaultLimit: 20,          // Default page size (default: 20)
    maxLimit: 100,             // Max page size (default: 100)

    // Soft delete — marks as deleted instead of removing
    softDelete: { field: "deletedAt" },

    // Lifecycle hooks
    hooks: {
        beforeCreate: (data) => ({ ...data, slug: slugify(data.title) }),
        beforeUpdate: (data) => ({ ...data, updatedAt: new Date() }),
    },
});

createCrud(tasks, {
    realtime: {
        policy: "authorized", // or "public"
        resourceIdentity: "tasks",
        scope: (args) => ({ workspaceId: args?.filters?.workspaceId }),
        scopeFromRow: ({ row, ctx }) => ({ workspaceId: row.workspaceId }),
        authorize: async ({ ctx, args }) => {
            const session = ctx.auth.requireAuth();
            await assertWorkspaceMember(ctx.db, session.user.id, args?.filters?.workspaceId);
        },
    },
});

// Backend: enable filtering by status and category
export const { list } = createCrud(tasks, {
    allowedFilters: ["status", "category"],
});

// Frontend: pass filters
const activeTasks = useQuery(api.tasks.list, {
    filters: { status: "active" },
});

const techPosts = useQuery(api.tasks.list, {
    filters: { status: "published", category: "tech" },
});

// ⚠️ Security: filters NOT in allowedFilters are silently ignored
// filters: { userId: "hacker" }  → ignored (userId not in allowedFilters)
// ⚠️ Secure by Default: if allowedFilters is NOT set, ALL filters are ignored

// Simple equality (implicit eq — backward compatible)
useQuery(api.tasks.list, { filters: { status: "active" } });

// Explicit operator syntax
useQuery(api.tasks.list, { filters: { status: { op: "eq", value: "active" } } });
useQuery(api.tasks.list, { filters: { status: { op: "ne", value: "draft" } } });
useQuery(api.tasks.list, { filters: { priority: { op: "gte", value: 3 } } });
useQuery(api.tasks.list, { filters: { category: { op: "in", value: ["tech", "news"] } } });
useQuery(api.tasks.list, { filters: { title: { op: "ilike", value: "%meeting%" } } });

// OR — match any condition
useQuery(api.tasks.list, {
    filters: {
        OR: [
            { status: "active" },
            { status: "review" },
        ],
    },
});

// AND — match all conditions (explicit; multiple top-level keys are implicitly AND)
useQuery(api.tasks.list, {
    filters: {
        AND: [
            { status: "active" },
            { priority: { op: "gte", value: 3 } },
        ],
    },
});

// Nested — OR within AND (max 5 levels deep)
useQuery(api.tasks.list, {
    filters: {
        AND: [
            { OR: [{ category: "tech" }, { category: "news" }] },
            { status: { op: "ne", value: "archived" } },
        ],
    },
});

// gencow/runtime.ts
import {
  createCrudFactory,
  createGencowHttpRouteBuilders,
  createGencowProcedureBuilders,
} from "@gencow/core";
import type { GencowSchema } from "./generated/db-schema.gen";

export const procedure = createGencowProcedureBuilders<GencowSchema>();
export const httpRoute = createGencowHttpRouteBuilders<GencowSchema>();
export const createCrud = createCrudFactory(procedure);

// gencow/tasks.ts
import { procedure } from "./runtime";
import { v } from "@gencow/core";

export const listMine = procedure.query
    .name("tasks.listMine")
    .handler(async ({ context }) => {
        const user = context.auth.requireAuth();
        return context.db.select().from(tasks).where(eq(tasks.userId, user.id));
    });

export const createOne = procedure.mutation
    .name("tasks.createOne")
    .input(v.object({ title: v.string() }))
    .handler(async ({ context, input }) => {
        const user = context.auth.requireAuth();
        return context.db.insert(tasks).values({ title: input.title, userId: user.id });
    });

export const cleanupOldTasks = procedure.internal
    .name("tasks.cleanupOld")
    .handler(async ({ context }) => {
        await context.db.delete(tasks).where(eq(tasks.done, true));
    });

// gencow/runtime.ts
import type { GencowSchema } from "./generated/db-schema.gen";
import { createGencowWorkflowBuilders } from "@gencow/core";

export const workflow = createGencowWorkflowBuilders<GencowSchema>();

// gencow/imports.ts
import { v } from "@gencow/core";
import { workflow } from "./runtime";

export const runImport = workflow
    .name("imports.run")
    .input(v.object({
        sourceId: v.string(),
        requireApproval: v.optional(v.boolean()),
    }))
    .maxDuration("30m")
    .retries(3)
    .handler(async (wf, args) => {
        const prepared = await wf.step("prepare", async () => {
            return { sourceId: args.sourceId, startedAt: new Date().toISOString() };
        });

        if (args.requireApproval) {
            const approval = await wf.waitForEvent<{ approved: boolean }>("approval", "24h");
            if (approval.approved !== true) return { ok: false, reason: "declined" };
        }

        return wf.step("finalize", async () => ({ ok: true, prepared }));
    });

// gencow/index.ts
import { defineApi } from "@gencow/core";
import { runImport } from "./imports";

export default defineApi({ workflows: { runImport } });

export const runTenantImport = workflow
    .name("imports.tenantRun")
    .input(v.object({ sourceId: v.string() }))
    .use(async ({ context, input, next }) => {
        await assertTenantMayImport(context.auth, input.sourceId);
        return next();
    })
    .concurrency(3)
    .handler((wf, input) => wf.step("import", () => importSource(input.sourceId)));

// Deprecated legacy API.
import { workflow, v } from "@gencow/core";

export const legacyRunImport = workflow("imports.legacyRun", {
    args: { sourceId: v.string() },
    handler: (wf, args) => wf.step("import", () => importSource(args.sourceId)),
});

// gencow/runtime.ts
import type { GencowSchema } from "./generated/db-schema.gen";
import { createGencowRealtimeChannelBuilder } from "@gencow/core";

export const realtimeChannel = createGencowRealtimeChannelBuilder<GencowSchema>();

// gencow/conversation-events.ts
import { v } from "@gencow/core";
import { realtimeChannel } from "./runtime";

export const conversationEvents = realtimeChannel
    .name("conversation.events")
    .input(v.object({ conversationId: v.string() }))
    .event(v.object({
        type: v.literal("message.created"),
        message: v.object({ id: v.string(), body: v.string() }),
    }))
    .channelKey(({ conversationId }) => `conversation:${conversationId}`)
    .authorize(async ({ context, input }) => {
        const user = context.auth.requireAuth();
        const membership = await requireConversationMember(context.db, user.id, input);
        return { ttlSeconds: 300, epoch: membership.epoch };
    });

// gencow/index.ts
import { defineApi } from "@gencow/core";
import { conversationEvents } from "./conversation-events";

export default defineApi({ realtimeChannels: { conversationEvents } });

// Inside an authorized backend handler. Check writer permissions before this.
await ctx.realtime.channel(conversationEvents, { conversationId }).publish({
    type: "message.created",
    message: { id: message.id, body: message.body },
});

await ctx.realtime.channel(conversationEvents, { conversationId }).revoke({
    epoch: nextMembershipEpoch,
    reason: "membership_changed",
});

useRealtimeChannel(
    { channel: api.realtimeChannels.conversationEvents, args: { conversationId } },
    (event) => console.log(event.message.body),
);

// Deprecated legacy API.
import { defineRealtimeChannels, v } from "@gencow/core";

defineRealtimeChannels({
    "conversation.events": {
        args: v.object({ conversationId: v.string() }),
        authorize: (ctx) => {
            ctx.auth.requireAuth();
            return { ttlSeconds: 300 };
        },
    },
});

ctx.realtime.channel("conversation.events", { conversationId }).publish(event);

// gencow/runtime.ts
import type { GencowSchema } from "./generated/db-schema.gen";
import { createGencowHttpRouteBuilders } from "@gencow/core";

export const httpRoute = createGencowHttpRouteBuilders<GencowSchema>();

// gencow/http-routes.ts (or index.ts)
import { defineApi } from "@gencow/core";
import { httpRoute } from "./runtime";
import { z } from "zod";

// GET /api/health — public, no schema
const health = httpRoute.get
    .path("/api/health")
    .allowAnonymous()
    .handler(async () => ({ body: { status: "ok" } }));

// POST /api/echo — typed input + output
const echo = httpRoute.post
    .path("/api/echo")
    .allowAnonymous()
    .input(z.object({ message: z.string() }))
    .output(z.object({ echoed: z.string(), length: z.number() }))
    .handler(async ({ input }) => ({
        body: { echoed: input.message, length: input.message.length },
    }));

// GET /api/tasks/:id — path params, authenticated by default
const taskById = httpRoute.get
    .path("/api/tasks/:id")
    .handler(async ({ context, request }) => {
        context.auth.requireAuth();
        const id = Number(request.params.id);
        if (!Number.isFinite(id)) return { status: 400, body: { error: "id must be a number" } };
        const [row] = await context.db.select().from(tasks).where(eq(tasks.id, id));
        return row ? { body: row } : { status: 404, body: { error: "not found" } };
    });

export default defineApi({
    httpRoutes: { health, echo, taskById },
});

async ({ context, input, request }) => HttpRouteResult<TOutput>

const traced = httpRoute.post
    .path("/api/traced")
    .allowAnonymous()
    .use(async ({ request, next }) => {
        const start = Date.now();
        const traceId = request.headers["x-trace-id"] ?? crypto.randomUUID();
        const result = await next();
        return {
            ...result,
            headers: {
                ...(result.headers ?? {}),
                "x-trace-id": traceId,
                "x-duration-ms": String(Date.now() - start),
            },
        };
    })
    .input(z.object({ name: z.string() }))
    .handler(async ({ input }) => ({ body: { greeting: `hello ${input.name}` } }));

chain:    use(mwA) → use(mwB) → input(schema) → use(mwC) → handler
                                       │
                                       └─ runs HERE during execution

happy path execution flow:

  mwA.before  →  mwB.before  →  [validate input]  →  mwC.before  →  handler
                                                                       ↓
  mwA.after   ←  mwB.after   ←  ─────────────────  ←  mwC.after   ←  ─┘

failure path (input schema rejects):

  mwA.before  →  mwB.before  →  [validate input] ✗
                                       │
                                       ↓
                              400 returned to client
                              (mwC, handler, mwA.after, mwB.after are SKIPPED)

export default defineApi({
    procedures: {
        listMine,
        createOne,
        tasksList: tasksCrud.list,
        tasksGet: tasksCrud.get,
        tasksCreate: tasksCrud.create,
        tasksUpdate: tasksCrud.update,
        tasksRemove: tasksCrud.remove,
    },
    httpRoutes: { health, echo, taskById },
});

handler: async (ctx, args) => {
    // Database (RLS injected automatically)
    ctx.db                    // Drizzle ORM instance (filtered)
    ctx.unsafeDb              // System-plane Drizzle instance (audited admin/system only)

    // Auth
    ctx.auth.requireAuth()    // Returns session (throws if not authed)
    ctx.auth.getSession()     // Returns session or null

    // Storage
    ctx.storage.store(file)              // Store private file -> storageId
    ctx.storage.createReadGrant(id)      // Short-lived private browser URL
    ctx.storage.getPublicUrl(id)         // Bare URL for public objects
    ctx.storage.delete(id)               // Delete file

    // Retrieval / RAG
    ctx.search("rag_chunks", query, options)       // Keyword search
    ctx.vectorSearch("rag_chunks", options)        // Vector search
    ctx.hybridSearch("rag_chunks", query, options) // Keyword + vector fusion
    ctx.grounding?.answer(input)                   // Grounded claims + citations

    // Workflow-only document conversion
    wf.services.document.convert(input)            // Only inside a workflow handler

    // Scheduler
    ctx.scheduler.runAfter(delayMs, "mutation.name", args)
    ctx.scheduler.runAt(timestamp, "mutation.name", args)

    // AI (generated gencow/ai.ts)
    // After: gencow add AI
    import { ai } from "./ai";
    ai.chat({ system, messages })     // → { text, usage, creditsCharged, model }
    ai.stream({ system, messages })   // → AsyncIterable<string>
    ai.embed(text)                    // → number[]
    ai.rerank({ query, documents, topK }) // → ranked candidates (Azure Cohere Fast in cloud)
    ai.vision.extractText({ image, mediaType }) // → { text, markdown?, usage, creditsCharged, model }
    ai.speech.transcribe({ storageId, model: "gpt-4o-mini-transcribe" }) // → async STT job
    ai.speech.synthesize({ input, model: "gpt-4o-mini-tts", voice: "alloy" }) // → private audio

    // Realtime (custom procedures only — createCrud() handles this automatically)
    ctx.realtime.invalidate("queryKey")     // Signal subscribers to refetch with their auth/args
    ctx.realtime.refresh("queryKey")        // Re-run server-safe query + push result
    ctx.realtime.emit("queryKey", data)     // Push data directly to public/opaque subscribers

    // File Upload (in mutation with FormData)
    // File is accessed via args, NOT ctx:
    const file = args?.["file"] as File;    // from FormData upload
    await ctx.storage.store(file);          // store to disk
}

import { eq, and, desc } from "drizzle-orm";
import { tasks } from "./schema";

// SELECT — Postgres RLS automatically filters
const rows = await ctx.db.select().from(tasks); // only current user's tasks

// SELECT with additional WHERE — combined with RLS
const done = await ctx.db.select().from(tasks).where(eq(tasks.done, true));

// INSERT — passes through (no filter needed for new rows)
const [row] = await ctx.db.insert(tasks).values({ title: "..." }).returning();

// UPDATE — filter auto-applied (can only update own rows)
await ctx.db.update(tasks).set({ done: true }).where(eq(tasks.id, 1));

// DELETE — filter auto-applied
await ctx.db.delete(tasks).where(eq(tasks.id, 1));

// ❌ Blocked — raw SQL not allowed on scoped db
ctx.db.execute(sql`SELECT * FROM tasks`); // throws Error

// ⚠️ Only for intentional filter bypass — flagged in security audits
const allTasks = await ctx.unsafeDb.select().from(tasks);
ctx.unsafeDb.execute(sql`TRUNCATE tasks`); // raw SQL allowed

// Require authentication (throws 401 if not logged in)
const session = ctx.auth.requireAuth();
// session.user.id    — User ID
// session.user.email — User email
// session.user.name  — User name

// Optional authentication
const session = ctx.auth.getSession();
// null if not authenticated

// Store a private file
const storageId = await ctx.storage.store(file, "optional-filename");

// Store from buffer
const storageId = await ctx.storage.storeBuffer(buffer, "name.pdf", "application/pdf");

// Create a private preview URL
const readGrant = await ctx.storage.createReadGrant(storageId, {
    ttlSeconds: 300,
    disposition: "inline",
});

// Store an intentionally public asset
const publicId = await ctx.storage.store(file, { visibility: "public" });
const publicUrl = ctx.storage.getPublicUrl(publicId);
// -> "/api/storage/<uuid>"

// Change visibility later
await ctx.storage.setVisibility(storageId, "public");
await ctx.storage.setVisibility(storageId, "private");

// Get metadata
const meta = await ctx.storage.getMeta(storageId);
// -> { id, name, size, type, visibility }

// Delete (also removes all cached image transforms)
await ctx.storage.delete(storageId);

// Public URL — Auto WebP applied if browser supports it
const url = ctx.storage.getPublicUrl(publicId);
// -> "/api/storage/<uuid>"
// Browser with WebP support → served as WebP (smaller)
// Browser without WebP     → served as original

// Explicit transform parameters (Pro and Scale plans)
// Append query params to the URL:
const thumb = `${url}?w=200`;              // 200px wide thumbnail
const hero  = `${url}?w=1200&q=85&f=webp`; // hero image optimized

const grant = await ctx.storage.createReadGrant(storageId);
const thumb = `${grant.url}&w=200`;

const keyword = await ctx.search("rag_chunks", "refund policy", {
    fields: ["chunk_text", "lexical_text"],
    scope: { corpus: "manuals", visibility: "shared" },
    limit: 10,
});

const semantic = await ctx.vectorSearch("rag_chunks", {
    vector: embedding,
    vectorField: "embedding",
    scope: { corpus: "manuals", visibility: "shared" },
    limit: 10,
});

const hybrid = await ctx.hybridSearch("rag_chunks", "refund policy", {
    fields: ["chunk_text", "lexical_text"],
    vector: embedding,
    vectorField: "embedding",
    scope: { corpus: "manuals", visibility: "shared" },
    tuning: {
        keywordCandidateLimit: 40,
        vectorCandidateLimit: 40,
        fusion: { mode: "rrf" },
    },
});

const result = await ctx.grounding?.answer({
    question: "What is the refund window?",
    scope: { corpus: "manuals", visibility: "shared" },
    claims: [
        {
            claimText: "Refunds are allowed within seven days.",
            requiredTerms: ["refunds", "seven days"],
        },
    ],
    mode: "qa",
});

if (!result?.grounded) {
    // Show an insufficient-evidence state instead of a fully grounded answer.
}

import { v } from "@gencow/core";
import { workflow } from "./runtime";

export const convertManual = workflow
    .name("manuals.convert")
    .input(v.object({
        storageId: v.string(),
        filename: v.string(),
    }))
    .handler(async (wf, { storageId, filename }) => {
        return wf.services.document.convert({
            storageId,
            filename,
            mimeType: "application/pdf",
            corpus: "manuals",
            visibility: "shared",
            mode: "force-ocr",
            provider: "auto",
        });
    });

PDF auto:
  kordoc
  -> OpenDataLoader
  -> stop with DOCUMENT_PAID_FALLBACK_REQUIRED

HWP/HWPX/HWPML/DOCX/XLSX auto:
  kordoc
  -> OpenDataLoader
  -> stop with DOCUMENT_PAID_FALLBACK_REQUIRED

TXT/Markdown/HTML/CSV auto:
  local_text

await wf.services.document.convert({
    storageId,
    filename: "report.pdf",
    mimeType: "application/pdf",
    corpus: "manuals",
    visibility: "shared",
    provider: "auto",
    paidFallback: true,
    maxServiceCredits: 500,
});

await wf.services.document.convert({
    storageId,
    filename: "scan.pdf",
    mimeType: "application/pdf",
    corpus: "manuals",
    visibility: "shared",
    mode: "force-external",
    provider: "openai",
    maxServiceCredits: 500,
});

// Run after delay (milliseconds)
await ctx.scheduler.runAfter(0, "emails.send", { to: "user@example.com" });
await ctx.scheduler.runAfter(60_000, "tasks.cleanup", {}); // 1 minute later

// Run at specific time
await ctx.scheduler.runAt(new Date("2026-03-27T09:00:00"), "reports.generate", {});

export const processNextBatch = procedure.internal
    .name("import.processNextBatch")
    .input(v.object({ importId: v.string(), cursor: v.optional(v.string()) }))
    .handler(async ({ context: ctx, input }) => {
        const batch = await loadBatch(input);
        await writeRows(ctx.db, batch.rows);

        if (batch.nextCursor) {
            await ctx.scheduler.runAfter(0, "import.processNextBatch", {
                importId: input.importId,
                cursor: batch.nextCursor,
            });
        }
    });

// invalidate() — clients refetch with their own auth and query args
// Best for private/RLS lists and general CRUD-style updates
ctx.realtime.invalidate("tasks.list");

// refresh() — re-runs the query handler on the server, pushes result
// Best for public/server-safe aggregate queries
ctx.realtime.refresh("dashboard.stats");

// emit() — pushes specific data directly (skip re-query)
// Best for public or opaque-token exact channels where you already have fresh data
ctx.realtime.emit("chat.getMessages", freshMessages);

import { v } from "@gencow/core";

{
    args: {
        title: v.string(),
        count: v.number(),
        active: v.boolean(),
        tags: v.array(v.string()),
        config: v.optional(v.object({
            theme: v.string(),
            limit: v.number(),
        })),
    },
}

import { cron, defineApi } from "@gencow/core";
import { procedure } from "./runtime";

export const syncData = procedure.internal
    .name("data.sync")
    .handler(async ({ context }) => {
        // server-only scheduled work
    });

export const syncDataCron = cron.name("syncData").interval({ minutes: 30 }).handler(syncData);
export const morningSyncCron = cron.name("morningSync").daily({ hour: 9 }).handler(syncData);

export default defineApi({
    procedures: { syncData },
    crons: { syncDataCron, morningSyncCron },
});

import { defineAuth } from "@gencow/core";

export default defineAuth({
    emailAndPassword: { enabled: true },
    // emailVerification: { ... },
});

import { withRetry } from "@gencow/core";

const result = await withRetry(
    () => fetch("https://api.example.com/data"),
    { maxAttempts: 3, initialBackoffMs: 1000 }
);

// ❌ WRONG — no unique constraint, onConflictDoNothing is meaningless
export const articles = pgTable("articles", {
    id: serial("id").primaryKey(),
    url: text("url").notNull(),
});

await ctx.db.insert(articles)
    .values({ url: "https://..." })
    .onConflictDoNothing();          // ← silently does nothing useful!

// ✅ CORRECT — add unique() constraint on url
export const articles = pgTable("articles", {
    id: serial("id").primaryKey(),
    url: text("url").notNull().unique(),  // ← unique constraint required
});

await ctx.db.insert(articles)
    .values({ url: "https://..." })
    .onConflictDoNothing({ target: articles.url });  // ← now works correctly

// Frontend — latest 1 record
const latest = useQuery(api.logs.list, { limit: 1, orderBy: "createdAt", orderDir: "desc" });
const latestLog = latest?.data[0];  // first (and only) item

// Frontend — latest with filter
const latestActive = useQuery(api.tasks.list, {
    limit: 1,
    filters: { status: "active" },
});