diff --git a/.agents/skills/graphile-file-urls/SKILL.md b/.agents/skills/graphile-file-urls/SKILL.md new file mode 100644 index 0000000000..a3ef2bb60b --- /dev/null +++ b/.agents/skills/graphile-file-urls/SKILL.md @@ -0,0 +1,81 @@ +--- +name: graphile-file-urls +description: Read URLs for a file-reference column (an `image` or `upload` jsonb domain column, scalar or array) from GraphQL — `Url(width)` and `Versions` returning `FileVersion`, added by graphile-presigned-url-plugin. Use when asked to "show an image at a size", "get a thumbnail URL", "get the URL of an uploaded file on a row", "srcset", "why is photoUrl null", or when adding a new file-reference domain (`fileRefDomains`). +compatibility: PostGraphile v5, graphile-presigned-url-plugin, graphile-storage-registry +metadata: + author: constructive-io + version: "1.0.0" +--- + +# File-reference column URLs + +Source: `graphile/graphile-presigned-url-plugin/src/file-ref-urls.ts` +(`createFileRefUrlsPlugin`, installed by `PresignedUrlPreset`). + +## What you get + +For every column whose type is a jsonb domain named in `FILE_REF_DOMAINS` +(`['image', 'upload']`, `graphile/graphile-storage-registry/src/naming.ts`), or +an array of one, the row type gains two fields: + +```graphql +type Product { + photo: JSON + photoUrl(width: Int): String # image or upload column + photoVersions: [FileVersion!] + gallery: [JSON] + galleryUrl(width: Int): [String] # array column: one entry per element + galleryVersions: [[FileVersion!]] +} + +type FileVersion { + name: String + key: String! + width: Int + height: Int + format: String + size: Int + url: String! +} +``` + +- `Url` without `width`: the source file's URL. +- `Url(width: N)`: the narrowest rendered version at least `N` wide; when + no version is that wide (or the document has none, as on an `upload` + column), the source URL. +- `Versions`: the versions in the document, narrowest first, each with a + URL. Empty when there are none. Use it for `srcset`. +- `null` when the file id is unknown, hidden from the reader by RLS, not live, + or its bucket is not reconciled. + +```graphql +{ products { nodes { photoUrl(width: 480) photoVersions { width url } resumeUrl } } } +``` + +Use these on business tables. `downloadUrl` is the field on a files-table row; +it is still there and behaves the same for bucket handling (public bucket with +`publicUrlPrefix` → direct URL, private → presigned GET). + +## Rules the resolver keeps + +- The file row is read by the document's `id` under the reader's RLS. The + document's own `key`, bucket and filename are ignored. +- A version is signed only if its key is a direct child of that row's + `.versions/` (`isVersionKeyOf`). Anything else in the document's + `versions` is dropped. +- `.versions/` is reserved: a client-supplied upload key containing it is + refused with `INVALID_KEY` (`src/custom-key.ts`). +- Lookups are batched per request: one files query per storage module for all + rows of a list, not one per row. + +## Adding a file type + +Pass the full list as the plugin option `fileRefDomains` (`src/types.ts`), or +add the name to `FILE_REF_DOMAINS`. The domain must be a jsonb domain whose +document carries the files row `id`. Do not add a per-type plugin. + +## Where versions come from + +The database writes them: constructive-db's `ProcessImageVersions` lane stores +`versions` inside the image document. This plugin only reads the document; a +column with no versions still resolves `Url` to the source. diff --git a/.agents/skills/graphile-search/SKILL.md b/.agents/skills/graphile-search/SKILL.md index 54e028c88e..9b5a737247 100644 --- a/.agents/skills/graphile-search/SKILL.md +++ b/.agents/skills/graphile-search/SKILL.md @@ -267,6 +267,7 @@ This avoids the problem of BM25/pgvector producing unbounded scores that can't b | `includeChunks` field missing | No `@hasChunks` tables in schema | Add `@hasChunks` smart tag to parent table codec | | `Unknown type "FullText"` | TsvectorCodecPlugin not loaded | Use `UnifiedSearchPreset()` which includes all codecs | | `Unknown type "Vector"` | VectorCodecPlugin not loaded | Use `UnifiedSearchPreset()` which includes all codecs | +| Vector search returns nothing after changing the embedding model | Rows are stamped with the old model in the `@embeddingModelOf` column | Re-embed the rows; see `references/pgvector-adapter.md` | | Duplicate type errors | Multiple search presets | Use only `UnifiedSearchPreset()`, not individual presets | ## Related Skills diff --git a/.agents/skills/graphile-search/references/pgvector-adapter.md b/.agents/skills/graphile-search/references/pgvector-adapter.md index e35ab95b4d..3c04235eed 100644 --- a/.agents/skills/graphile-search/references/pgvector-adapter.md +++ b/.agents/skills/graphile-search/references/pgvector-adapter.md @@ -189,6 +189,36 @@ query { } ``` +## Model-Aware Search (`@embeddingModel` / `@embeddingModelOf`) + +Vectors of two models are not comparable. The adapter reads two smart tags +(`graphile/graphile-search/src/adapters/pgvector.ts`, `detectColumns`): + +| Tag | On | Meaning | +|-----|----|---------| +| `@embeddingModel ` | the vector column | the model the column's definition names | +| `@embeddingModelOf ` | a sibling text column | records, per row, the model that produced that row's vector | + +constructive-db's `SearchVector` generator emits both (`_model` carries +`@embeddingModelOf`; `@embeddingModel` only when the node names a model). + +- The vector filter input has a `model` field. On a column with a model + column, when `model` is given only rows whose stamp equals it are compared; + rows stamped with another model (or not stamped) are skipped until they are + embedded again with that model. +- With `graphile-llm`, a search `text` is embedded once per model its columns + use (`@embeddingModel`, else the request's model) and `model` is filled in + server-side (`graphile/graphile-llm/src/embed-inputs.ts`). A column whose + embedding failed sits the search out; it is never searched with another + model's vector. +- On write, `graphile-llm`'s `Text` mutation input embeds with the + column's `@embeddingModel` and, when the `@embeddingModelOf` column is in + the mutation input, writes the model used into it + (`graphile/graphile-llm/src/plugins/text-mutation-plugin.ts`). +- Passing a raw `vector` yourself: pass `model` too, or rows of every model + are compared. +- A column with neither tag behaves as before. + ## VectorCodecPlugin The `VectorCodecPlugin` (included in `UnifiedSearchPreset`) teaches PostGraphile about the `vector` PostgreSQL type: diff --git a/AGENTS.md b/AGENTS.md index 8857e1771f..f3d8956001 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -175,6 +175,7 @@ The `.agents/skills/` directory contains tooling-focused skills for this monorep | `constructive-testing` | PostgreSQL testing frameworks — pgsql-test, drizzle-orm-test, supabase-test | Writing database tests, testing RLS policies, seeding test data | | `constructive-cli` | Generated CLI commands — how the CLI is generated from GraphQL schemas, codegen options, multi-target CLI | Generating CLI tools, running generated CLI, understanding codegen pipeline | | `graphile-search` | Unified PostGraphile v5 search plugin — tsvector, BM25, pg_trgm, pgvector adapters, composite searchScore | Adding search to GraphQL, configuring search adapters, querying search via SDK | +| `graphile-file-urls` | `Url(width)` / `Versions` / `FileVersion` on `image` and `upload` columns (graphile-presigned-url-plugin) | Reading a sized image URL or an uploaded file's URL from a business-table row, adding a file-reference domain | ## Tips