feat: add pluggable friction stores

.changeset/calm-frogs-store.md

@@ -0,0 +1,7 @@
+---
+'frog': minor
+---
+
+Add a public friction-store contract, a storage-independent `FrictionLog` API, and an optional
+Postgres adapter while preserving the repository file store as the default. `FROG_DATABASE_URL`
+automatically selects Postgres for CLI commands, and `frog migrate` prepares the selected store.

README.md

@@ -180,6 +180,47 @@ ships a reproduction. Exits 1 on an entry that fails to parse, so it doubles as
 frog list
 ```
 
+### Store Logs in Postgres
+
+Frog stores entries in `.agents/friction-log/` by default. Set `FROG_DATABASE_URL` to use Postgres
+instead, then run the idempotent migration once:
+
+```sh
+FROG_DATABASE_URL=postgres://... frog migrate
+FROG_DATABASE_URL=postgres://... frog list
+```
+
+Install `pg` beside Frog when using Postgres (and `@types/pg` in TypeScript projects).
+`FROG_NAMESPACE` can isolate several consumers in one database (it defaults to `default`), and
+`FROG_SCHEMA` can place the table in a specific schema. An unrelated application `DATABASE_URL` does
+not change Frog's default store.
+
+Applications use the same store through the programmatic API:
+
+```ts
+import { FrictionLog, PostgresStore } from 'frog'
+import { Pool } from 'pg'
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL })
+await PostgresStore.migrate({ client: pool })
+const store = PostgresStore.adapter({ client: pool, namespace: 'support-agent' })
+const frog = new FrictionLog({ store })
+
+const result = await frog.record({
+  title: 'Search result omitted its freshness',
+  body: 'The caller could not tell when the result was collected.',
+  severity: 'major',
+  context: { source: 'production-agent', execution: 'opaque-reference' },
+})
+
+const unresolved = await frog.records() // canonical entries with deduplicated occurrence counts
+```
+
+Every store implements the exported `FrictionStore` contract and preserves the same `Entry` fields.
+Storage metadata such as occurrence counts stays outside that entry schema. Custom adapters can use a
+remote service, SQLite, or another database. Repository and GitHub automation—artifacts, `list --since`,
+`log --open`, `log --publish`, `publish`, and `sync`—remains available only with the file store.
+
 ### Logging Upstream
 
 Reports friction to another project instead of your own. A target is an npm package or an `owner/repo`,
@@ -224,7 +265,9 @@ Commands:
   init     Create the friction log, config, and issue form.
   list     List entries with their state.
   log      Write a friction entry.
+  migrate  Create or upgrade the selected store.
   publish  Report pending entries as GitHub issues.
+  resolve  Remove one resolved friction entry.
   sync     Reconcile entries against issue state.
   targets  List dependencies that accept friction reports.
 

package.json

@@ -64,6 +64,14 @@
     "incur": "catalog:",
     "yaml": "catalog:"
   },
+  "peerDependencies": {
+    "pg": ">=8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "pg": {
+      "optional": true
+    }
+  },
   "engines": {
     "node": ">=22"
   }

src/Entry.ts

@@ -16,6 +16,8 @@ export const Severity = z.enum(severities)
 
 /** Frontmatter of an entry's write-up. */
 export type Frontmatter = {
+  /** Consumer-defined structured context. Frog stores it but does not interpret it. */
+  context?: Readonly<Record<string, unknown>> | undefined
   /** Linked issue as `owner/name#number`. Written by publishing, absent while pending. */
   issue?: string | undefined
   /** Extra issue labels, applied on top of the configured and severity labels. */
@@ -39,6 +41,7 @@ export type Frontmatter = {
  * annotation stops the hand-written type and the schema drifting.
  */
 export const Frontmatter: z.ZodType<Frontmatter> = z.object({
+  context: z.record(z.string(), z.unknown()).optional(),
   issue: z
     .string()
     .regex(/^[\w.-]+\/[\w.-]+#\d+$/)
@@ -121,11 +124,12 @@ export declare namespace parse {
  * @returns File contents, ready to write. Absent optional fields are omitted, not written empty.
  */
 export function serialize(entry: serialize.Options): string {
-  const { body, issue, labels, severity, target, title } = entry
+  const { body, context, issue, labels, severity, target, title } = entry
   const frontmatter = YAML.stringify(
     {
       title,
       severity,
+      ...(context && Object.keys(context).length ? { context } : {}),
       ...(target ? { target } : {}),
       ...(labels?.length ? { labels } : {}),
       ...(issue ? { issue } : {}),

src/FrictionLog.test.ts

@@ -0,0 +1,52 @@
+import { tmpdir } from '../test/helpers.js'
+import { FrictionLog } from './FrictionLog.js'
+
+const entry = {
+  body: 'It took an unnecessary workaround.',
+  severity: 'minor',
+  title: 'Filters ignored',
+} as const
+
+describe('FrictionLog', () => {
+  test('behavior: defaults to the existing repository-file store', async () => {
+    const log = new FrictionLog({ root: await tmpdir() })
+    const result = await log.record(entry)
+
+    expect(result).toMatchObject({ created: true, occurrences: 1 })
+    expect(log.store.name).toBe('file')
+    expect(await log.list()).toEqual([result.entry])
+    expect(await log.records()).toEqual([{ entry: result.entry, occurrences: 1 }])
+  })
+
+  test('behavior: deduplicates normalized titles without changing the file-store default', async () => {
+    const log = new FrictionLog({ root: await tmpdir() })
+    const first = await log.record(entry)
+    const repeated = await log.record({ ...entry, title: 'filters: ignored!' })
+
+    expect(repeated).toEqual({ created: false, entry: first.entry, occurrences: 1 })
+    expect(await log.list()).toHaveLength(1)
+  })
+
+  test('behavior: delegates atomic recording to an adapter that provides it', async () => {
+    const record = vi.fn(async () => ({
+      created: false,
+      entry: { ...entry, id: 'existing' },
+      occurrences: 4,
+    }))
+    const log = new FrictionLog({
+      store: {
+        name: 'custom',
+        record,
+        read: vi.fn(),
+        list: vi.fn(),
+        get: vi.fn(),
+        write: vi.fn(),
+        remove: vi.fn(),
+        files: vi.fn(),
+      },
+    })
+
+    await expect(log.record(entry)).resolves.toMatchObject({ created: false, occurrences: 4 })
+    expect(record).toHaveBeenCalledWith(entry, {})
+  })
+})