@ganju/utils 0.0.18 → 0.0.21

package/dist/dataCompiler.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isSensitiveWrite = exports.tidyArgs = exports.chunkRows = exports.rowsPerInsert = exports.keysetCondition = exports.decodeCursor = exports.encodeCursor = exports.ftsMatch = exports.assertParamCount = exports.compileWhere = exports.resolvePath = exports.fromStored = exports.zoned = exports.zoneOffsetMinutes = exports.toStored = exports.isoSeconds = exports.relationJoin = exports.joinsParams = exports.joinsSql = exports.participantOf = exports.canRead = exports.isScoped = exports.tableFor = exports.visibleTables = exports.accessOf = exports.unknownColumn = exports.columnFor = exports.isSystemColumn = exports.FILTER_OPERATORS = void 0;
+exports.isSensitiveWrite = exports.tidyArgs = exports.chunkRows = exports.rowsPerInsert = exports.keysetCondition = exports.decodeCursor = exports.encodeCursor = exports.ftsMatch = exports.assertParamCount = exports.compileWhere = exports.resolvePath = exports.fromStored = exports.zoned = exports.zoneOffsetMinutes = exports.toStored = exports.unknownFileUris = exports.fileUriOf = exports.isoSeconds = exports.relationJoin = exports.joinsParams = exports.joinsSql = exports.participantOf = exports.canRead = exports.isScoped = exports.tableFor = exports.visibleTables = exports.accessOf = exports.unknownColumn = exports.columnFor = exports.isSystemColumn = exports.FILTER_OPERATORS = void 0;
 // Turns the structured query and write arguments into SQL with bound values.
 // Identifiers are checked against the database's own schema and quoted;
 // every value a caller sends is a parameter. Pure: the engine runs the SQL.
@@ -162,6 +162,26 @@ const checkSize = (label, value) => {
     }
     return value;
 };
+// A knowledge item's uri, given as the text or as { uri } (how reads return
+// it). Any scheme: knowledge holds resource://, website and drive uris.
+const fileUriOf = (value, label) => {
+    const raw = value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value.uri
+        : value;
+    const uri = typeof raw === 'string' ? raw.trim() : '';
+    if (!/^[a-z][a-z0-9+.-]*:\/\/\S+$/i.test(uri)) {
+        throw new dataTypes_1.DataError(`${label} takes a knowledge item's uri, e.g. resource://menu-photo.`);
+    }
+    if (uri.length > dataTypes_1.DATA_FILE_URI_MAX) {
+        throw new dataTypes_1.DataError(`${label}: a uri is at most ${dataTypes_1.DATA_FILE_URI_MAX} characters.`, 'too_large');
+    }
+    return uri;
+};
+exports.fileUriOf = fileUriOf;
+// A write that links uris no item of the project has: the workers check,
+// since the database object can't see knowledge.
+const unknownFileUris = (uris) => new dataTypes_1.DataError(`No resource in this project has the uri ${uris.join(', ')}; link an existing resource by its uri.`, 'invalid', { uris });
+exports.unknownFileUris = unknownFileUris;
 // Turns a value from a caller into what the column stores, or explains why
 // it can't. `timeZone` is the project's, for datetimes sent without an
 // offset.
@@ -230,6 +250,8 @@ const toStored = (table, column, value, timeZone) => {
                 throw new dataTypes_1.DataError(`${label} must be a URL starting with http(s)://.`);
             }
             return checkSize(label, value.trim());
+        case 'file':
+            return (0, exports.fileUriOf)(value, label);
         case 'phone': {
             if (typeof value !== 'string' && typeof value !== 'number') {
                 throw new dataTypes_1.DataError(`${label} must be a phone number.`);
@@ -392,6 +414,8 @@ const compileWhere = (ctx, where, indexed) => {
             continue;
         }
         const resolved = (0, exports.resolvePath)(ctx, key);
+        if (resolved.own)
+            ctx.filtered?.add(resolved.column.name);
         // { "customer": { "name": "Ana" } } reads as "customer.name": models
         // write relation filters this way unprompted.
         if (resolved.column.type === 'relation' &&

package/dist/dataDdl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dataDdl.d.ts","sourceRoot":"","sources":["../src/dataDdl.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,UAAU,EACV,cAAc,EACd,gBAAgB,EAChB,SAAS,EACV,MAAM,aAAa,CAAC;AAErB,eAAO,MAAM,YAAY,0CAA0C,CAAC;AAEpE,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,cAAc,CAOtD,CAAC;AACH,eAAO,MAAM,aAAa,EAAE,WAAW,CAAC,cAAc,CAGpD,CAAC;AAEH,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,cAAc,CAOvD,CAAC;AAEH,eAAO,MAAM,YAAY,EAAE,WAAW,CAAC,cAAc,CAWnD,CAAC;AAIH,eAAO,MAAM,UAAU,GAAI,OAAO,gBAAgB,KAAG,MAQpD,CAAC;AAIF,eAAO,MAAM,SAAS,GAAI,OAAO,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,EAAE,QAAQ,UAAU,WAC3C,CAAC;AAChC,eAAO,MAAM,eAAe,GAC1B,OAAO,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,EAC5B,QAAQ,UAAU,WACc,CAAC;AACnC,eAAO,MAAM,oBAAoB,GAAI,OAAO,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,WACnC,CAAC;AAC/B,eAAO,MAAM,YAAY,GAAI,OAAO,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,WACrC,CAAC;AACvB,eAAO,MAAM,aAAa,GAAI,OAAO,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,WACvC,CAAC;AACpB,eAAO,MAAM,mBAAmB,GAAI,QAAQ,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,WAC9C,CAAC;AACrB,eAAO,MAAM,iBAAiB,GAAI,QAAQ,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,WAC5C,CAAC;AAGrB,eAAO,MAAM,aAAa,GACxB,QAAQ,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,EAChC,OAAO,gBAAgB,KACtB,gBAKF,CAAC;AA2CF,eAAO,MAAM,mBAAmB,GAAI,QAAQ,UAAU,KAAG,MAuBxD,CAAC;AAKF,eAAO,MAAM,cAAc,GACzB,MAAM,MAAM,EACZ,SAAS,SAAS,UAAU,EAAE,KAC7B,MAcW,CAAC;AAEf,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACb;AAMD,eAAO,MAAM,cAAc,GAAI,OAAO,SAAS,KAAG,cAAc,EA6B/D,CAAC;AAGF,eAAO,MAAM,eAAe,GAAI,QAAQ,UAAU,KAAG,OAI7B,CAAC;AAEzB,eAAO,MAAM,iBAAiB,GAAI,OAAO,SAAS,KAAG,UAAU,EAG5D,CAAC;AAKJ,eAAO,MAAM,YAAY,GAAI,OAAO,SAAS,KAAG,MAAM,GAAG,IAQxD,CAAC;AAkGF,eAAO,MAAM,eAAe,GAAI,OAAO,SAAS,KAAG,cAAc,EAIhE,CAAC;AAOF,eAAO,MAAM,aAAa,GACxB,UAAU,cAAc,EACxB,IAAI,UAAU,EACd,KAAK,MAAM,KACV,MAgCF,CAAC;AAIF,eAAO,MAAM,yBAAyB,GACpC,IAAI,UAAU,EACd,KAAK,MAAM,EACX,WAAW,MAAM,KAChB,MAyBF,CAAC"}
+{"version":3,"file":"dataDdl.d.ts","sourceRoot":"","sources":["../src/dataDdl.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,UAAU,EACV,cAAc,EACd,gBAAgB,EAChB,SAAS,EACV,MAAM,aAAa,CAAC;AAErB,eAAO,MAAM,YAAY,0CAA0C,CAAC;AAEpE,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,cAAc,CAOtD,CAAC;AACH,eAAO,MAAM,aAAa,EAAE,WAAW,CAAC,cAAc,CAGpD,CAAC;AAEH,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,cAAc,CAOvD,CAAC;AAEH,eAAO,MAAM,YAAY,EAAE,WAAW,CAAC,cAAc,CAWnD,CAAC;AAIH,eAAO,MAAM,UAAU,GAAI,OAAO,gBAAgB,KAAG,MAQpD,CAAC;AAIF,eAAO,MAAM,SAAS,GAAI,OAAO,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,EAAE,QAAQ,UAAU,WAC3C,CAAC;AAChC,eAAO,MAAM,eAAe,GAC1B,OAAO,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,EAC5B,QAAQ,UAAU,WACc,CAAC;AACnC,eAAO,MAAM,oBAAoB,GAAI,OAAO,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,WACnC,CAAC;AAC/B,eAAO,MAAM,YAAY,GAAI,OAAO,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,WACrC,CAAC;AACvB,eAAO,MAAM,aAAa,GAAI,OAAO,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,WACvC,CAAC;AACpB,eAAO,MAAM,mBAAmB,GAAI,QAAQ,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,WAC9C,CAAC;AACrB,eAAO,MAAM,iBAAiB,GAAI,QAAQ,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,WAC5C,CAAC;AAGrB,eAAO,MAAM,aAAa,GACxB,QAAQ,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,EAChC,OAAO,gBAAgB,KACtB,gBAKF,CAAC;AA2CF,eAAO,MAAM,mBAAmB,GAAI,QAAQ,UAAU,KAAG,MAuBxD,CAAC;AAKF,eAAO,MAAM,cAAc,GACzB,MAAM,MAAM,EACZ,SAAS,SAAS,UAAU,EAAE,KAC7B,MAcW,CAAC;AAEf,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACb;AAMD,eAAO,MAAM,cAAc,GAAI,OAAO,SAAS,KAAG,cAAc,EA6B/D,CAAC;AAGF,eAAO,MAAM,eAAe,GAAI,QAAQ,UAAU,KAAG,OAI7B,CAAC;AAEzB,eAAO,MAAM,iBAAiB,GAAI,OAAO,SAAS,KAAG,UAAU,EAG5D,CAAC;AAKJ,eAAO,MAAM,YAAY,GAAI,OAAO,SAAS,KAAG,MAAM,GAAG,IAQxD,CAAC;AAkGF,eAAO,MAAM,eAAe,GAAI,OAAO,SAAS,KAAG,cAAc,EAIhE,CAAC;AAOF,eAAO,MAAM,aAAa,GACxB,UAAU,cAAc,EACxB,IAAI,UAAU,EACd,KAAK,MAAM,KACV,MAgCF,CAAC;AAIF,eAAO,MAAM,yBAAyB,GACpC,IAAI,UAAU,EACd,KAAK,MAAM,EACX,WAAW,MAAM,KAChB,MA+BF,CAAC"}

package/dist/dataDdl.js

@@ -6,6 +6,7 @@ exports.invalidAfterConversionSql = exports.conversionSql = exports.desiredTrigg
 // ours, and every owner-supplied value is a literal escaped by sqlLiteral.
 const dataTriggers_1 = require("./dataTriggers");
 const dataIdentifiers_1 = require("./dataIdentifiers");
+const dataTypes_1 = require("./dataTypes");
 exports.DATA_NOW_SQL = "strftime('%Y-%m-%dT%H:%M:%SZ', 'now')";
 exports.TEXT_LIKE_TYPES = new Set([
     'text',
@@ -348,6 +349,10 @@ const invalidAfterConversionSql = (to, src, converted) => {
     if (to.type === 'url') {
         parts.push(`NOT ((${converted}) LIKE 'http://%' OR (${converted}) LIKE 'https://%')`);
     }
+    // A file column holds a knowledge item's uri: scheme://…, no spaces.
+    if (to.type === 'file') {
+        parts.push(`NOT ((${converted}) GLOB '[A-Za-z]*://?*' AND (${converted}) NOT GLOB '*[ ' || char(9) || char(10) || char(13) || ']*' AND length(${converted}) <= ${dataTypes_1.DATA_FILE_URI_MAX})`);
+    }
     if (to.type === 'relation' && to.table) {
         parts.push(`((${converted}) IS NOT NULL AND NOT EXISTS (SELECT 1 FROM ${(0, dataIdentifiers_1.quoteIdentifier)(to.table)} WHERE id = (${converted})))`);
     }

package/dist/dataEngine.d.ts

@@ -1,12 +1,15 @@
 import type { SqlValue } from './dataCompiler';
 import { toTableInput, DataError } from './dataTypes';
-import type { DataCaller, DataColumn, DataDefaultValue, DataDeleteImpact, DataSchema, DataTable, DataTableCopy } from './dataTypes';
+import type { DataCaller, DataColumn, DataDefaultValue, DataDeleteImpact, DataFileLinks, DataFileLinksReplaced, DataQueryShape, DataSchema, DataTable, DataTableCopy, DataUsage, DataWriteShape } from './dataTypes';
 export type SqlRow = Record<string, SqlValue>;
 export interface SqlRunner {
     all(sql: string, params?: readonly SqlValue[]): SqlRow[];
     iterate(sql: string, params?: readonly SqlValue[]): Iterable<SqlRow>;
     transaction<T>(fn: () => T): T;
     databaseSize(): number;
+    usageSoFar?(): DataUsage;
+    noteQuery?(shape: DataQueryShape): void;
+    noteWrite?(shape: DataWriteShape): void;
 }
 export declare const INTERNAL_MIGRATIONS: readonly (readonly string[])[];
 export declare const INTERNAL_SCHEMA_VERSION: number;
@@ -45,7 +48,7 @@ export declare const describe: (runner: SqlRunner, schema: DataSchema, caller: D
         rowsAbout: number;
         onlyThisCustomersRows?: boolean | undefined;
         description: string | null;
-        access: "none" | "read" | "add" | "full";
+        access: "none" | "add" | "read" | "full";
         label?: string | undefined;
         name: string;
     } | {
@@ -70,7 +73,7 @@ export declare const describe: (runner: SqlRunner, schema: DataSchema, caller: D
         rows: number;
         onlyThisCustomersRows?: boolean | undefined;
         description: string | null;
-        access: "none" | "read" | "add" | "full";
+        access: "none" | "add" | "read" | "full";
         label?: string | undefined;
         name: string;
     })[];
@@ -83,6 +86,7 @@ export declare const query: (runner: SqlRunner, schema: DataSchema, caller: Data
     nextCursor?: string | undefined;
     includeTruncated?: string | undefined;
     rows: ShapedRow[];
+    fileFields?: string[][] | undefined;
     searchMatched?: "all words" | "any word" | undefined;
     total?: number | undefined;
     scope?: string | undefined;
@@ -108,6 +112,8 @@ export declare const write: (runner: SqlRunner, schema: DataSchema, caller: Data
     results: WriteResult[];
 };
 export declare const deleteImpact: (runner: SqlRunner, schema: DataSchema, caller: DataCaller, rawArgs: unknown) => DataDeleteImpact;
+export declare const fileLinks: (runner: SqlRunner, schema: DataSchema, caller: DataCaller, rawArgs: unknown) => DataFileLinks;
+export declare const replaceFileLinks: (runner: SqlRunner, schema: DataSchema, caller: DataCaller, rawArgs: unknown) => DataFileLinksReplaced;
 export declare const rowHistory: (runner: SqlRunner, schema: DataSchema, caller: DataCaller, args: {
     table: string;
     id: number;

package/dist/dataEngine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dataEngine.d.ts","sourceRoot":"","sources":["../src/dataEngine.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dataEngine.d.ts","sourceRoot":"","sources":["../src/dataEngine.ts"],"names":[],"mappings":"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"}

package/dist/dataEngine.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.exportRows = exports.dropColumn = exports.updateColumn = exports.copyTableStep = exports.clearFailedTableCopy = exports.writeReachesCopy = exports.readTableCopy = exports.dropColumnNeedsRebuild = exports.columnChangeNeedsRebuild = exports.addColumn = exports.dropTable = exports.updateTable = exports.createTable = exports.pruneHistory = exports.rowHistory = exports.deleteImpact = exports.write = exports.assertWritable = exports.assertActor = exports.query = exports.describe = exports.translateSqliteError = exports.normaliseColumn = exports.toTableInput = exports.loadSchema = exports.migrateInternal = exports.setMeta = exports.getMeta = exports.hasInternalTables = exports.INTERNAL_SCHEMA_VERSION = exports.INTERNAL_MIGRATIONS = void 0;
+exports.exportRows = exports.dropColumn = exports.updateColumn = exports.copyTableStep = exports.clearFailedTableCopy = exports.writeReachesCopy = exports.readTableCopy = exports.dropColumnNeedsRebuild = exports.columnChangeNeedsRebuild = exports.addColumn = exports.dropTable = exports.updateTable = exports.createTable = exports.pruneHistory = exports.rowHistory = exports.replaceFileLinks = exports.fileLinks = exports.deleteImpact = exports.write = exports.assertWritable = exports.assertActor = exports.query = exports.describe = exports.translateSqliteError = exports.normaliseColumn = exports.toTableInput = exports.loadSchema = exports.migrateInternal = exports.setMeta = exports.getMeta = exports.hasInternalTables = exports.INTERNAL_SCHEMA_VERSION = exports.INTERNAL_MIGRATIONS = void 0;
 // What a project's database does, written against a tiny SQL runner so the
 // same code runs inside the Durable Object (apps/data) and on node:sqlite in
 // the tests and the tool-design eval. The runner executes; everything about
@@ -335,8 +335,11 @@ const normaliseColumn = (input, schema, selfTable) => {
     if (column.unique && !dataDdl_1.UNIQUE_TYPES.has(column.type)) {
         throw new dataTypes_1.DataError(`${label}: a ${column.type} column can't be unique.`);
     }
-    if (column.searchable && !dataDdl_1.SEARCHABLE_TYPES.has(column.type)) {
-        throw new dataTypes_1.DataError(`${label}: only text columns can be searchable (text, long_text, email, url, phone, enum).`);
+    // On a file column, searchable means its uploads are indexed in knowledge.
+    if (column.searchable &&
+        !dataDdl_1.SEARCHABLE_TYPES.has(column.type) &&
+        column.type !== 'file') {
+        throw new dataTypes_1.DataError(`${label}: only text and file columns can be searchable (text, long_text, email, url, phone, enum, file).`);
     }
     // The search table has a column of its own called rank.
     if (column.searchable && column.name === 'rank') {
@@ -548,6 +551,9 @@ const shapeRow = (schema, table, raw, caller) => {
                             : label
                     };
         }
+        else if (column.type === 'file') {
+            row[column.name] = value === null ? null : { uri: String(value) };
+        }
         else {
             row[column.name] = value;
         }
@@ -626,8 +632,19 @@ const query = (runner, schema, caller, rawArgs) => {
         caller,
         table,
         joins: new Map(),
-        params: []
+        params: [],
+        filtered: new Set()
     };
+    // What this query read, noted for index advice once it has its rows.
+    const readBefore = runner.usageSoFar?.().rowsRead ?? 0;
+    const sorted = [];
+    const noteShape = (returned) => runner.noteQuery?.({
+        table: table.name,
+        filtered: [...(ctx.filtered ?? [])],
+        sorted,
+        rowsRead: (runner.usageSoFar?.().rowsRead ?? 0) - readBefore,
+        returned
+    });
     const indexed = new Set();
     const where = (0, dataCompiler_1.compileWhere)(ctx, args.where, indexed);
     if ((0, dataCompiler_1.isScoped)(caller, table)) {
@@ -639,7 +656,10 @@ const query = (runner, schema, caller, rawArgs) => {
         throw new dataTypes_1.DataError(`"${table.name}" has no searchable columns; filter with "where" instead (e.g. { "name": { "contains": "..." } }).`);
     }
     if (args.aggregate !== undefined && args.aggregate !== null) {
-        return aggregate(runner, ctx, args, where, searching, indexed.size > 0);
+        const result = aggregate(runner, ctx, args, where, searching, indexed.size > 0);
+        const groups = result.groups;
+        noteShape(Array.isArray(groups) ? groups.length : 1);
+        return result;
     }
     const limit = args.limit === undefined || args.limit === null ? dataTypes_1.DATA_DEFAULT_PAGE : args.limit;
     if (typeof limit !== 'number' || !Number.isInteger(limit) || limit < 1 || limit > dataTypes_1.DATA_MAX_PAGE) {
@@ -672,6 +692,8 @@ const query = (runner, schema, caller, rawArgs) => {
             descending,
             ...(servedByIndex ? {} : { unindexed: resolved.column.name })
         });
+        if (resolved.own && resolved.column.name !== 'id')
+            sorted.push(resolved.column.name);
         if (resolved.own && resolved.column.name === 'id') {
             endsUnique = true;
             break;
@@ -763,14 +785,17 @@ const query = (runner, schema, caller, rawArgs) => {
         throw (0, exports.translateSqliteError)(schema, table, error);
     }
     const { rows: out, last, more } = result;
+    noteShape(out.length);
     const includeTruncated = args.include !== undefined && args.include !== null
         ? includeRelations(runner, schema, caller, table, out, args.include, dataTypes_1.DATA_MAX_RESULT_BYTES - result.bytes)
         : false;
+    const fileFields = fileFieldPaths(schema, table, args.include);
     return {
         table: table.name,
         ...((0, dataCompiler_1.isScoped)(caller, table) ? { scope: SCOPE_NOTE } : {}),
         ...(result.total !== undefined ? { total: result.total } : {}),
         ...(matched ? { searchMatched: matched } : {}),
+        ...(fileFields.length ? { fileFields } : {}),
         rows: out,
         ...(includeTruncated
             ? {
@@ -789,6 +814,25 @@ const query = (runner, schema, caller, rawArgs) => {
     };
 };
 exports.query = query;
+// Where a query's rows hold file values, as key paths within each row: the
+// table's file columns, and those of each included relation. The workers
+// fill those in from knowledge and drop this before answering; a json
+// column holding { "uri": … } is never mistaken for one.
+const fileFieldPaths = (schema, table, include) => {
+    const own = table.columns
+        .filter(column => column.type === 'file')
+        .map(column => [column.name]);
+    const included = (Array.isArray(include) ? include : []).flatMap(name => {
+        const column = typeof name === 'string' ? (0, dataCompiler_1.columnFor)(table, name) : undefined;
+        if (!column || (0, dataCompiler_1.isSystemColumn)(column) || column.type !== 'relation')
+            return [];
+        const target = schema.tables.find(t => t.name === column.table);
+        return (target?.columns ?? [])
+            .filter(c => c.type === 'file')
+            .map(c => [name, c.name]);
+    });
+    return [...own, ...included];
+};
 // Replaces each relation in `rows` named in `include` with the related row,
 // read as the caller may see it, within `budget` bytes. Returns whether any
 // was left as { id, label } to stay inside it.
@@ -1353,7 +1397,12 @@ const write = (runner, schema, caller, rawArgs) => {
         const results = [];
         operations.forEach((op, index) => {
             try {
+                const before = runner.usageSoFar?.().rowsWritten ?? 0;
                 results.push(runOperation(runner, schema, caller, op, index, results));
+                runner.noteWrite?.({
+                    table: results[results.length - 1].table,
+                    rowsWritten: (runner.usageSoFar?.().rowsWritten ?? 0) - before
+                });
             }
             catch (error) {
                 if (error instanceof dataTypes_1.DataError) {
@@ -1461,6 +1510,93 @@ const deleteImpact = (runner, schema, caller, rawArgs) => {
     };
 };
 exports.deleteImpact = deleteImpact;
+// File links
+const fileColumns = (schema) => schema.tables.flatMap(table => table.columns
+    .filter(column => column.type === 'file')
+    .map(column => ({ table, column })));
+const fileUriList = (value) => {
+    if (!Array.isArray(value) ||
+        value.length === 0 ||
+        value.length > dataTypes_1.DATA_FILE_LINKS_MAX_URIS) {
+        throw new dataTypes_1.DataError(`"uris" lists 1 to ${dataTypes_1.DATA_FILE_LINKS_MAX_URIS} knowledge item uris.`);
+    }
+    return [...new Set(value.map(uri => (0, dataCompiler_1.fileUriOf)(uri, 'uris')))];
+};
+// The rows whose file columns point at `uris`, per column: knowledge asks
+// before it deletes an item. Each file column is indexed.
+const fileLinks = (runner, schema, caller, rawArgs) => {
+    (0, exports.assertActor)(caller);
+    if (caller.restricted) {
+        throw new dataTypes_1.DataError('File links are for the owner.', 'forbidden');
+    }
+    const uris = JSON.stringify(fileUriList((0, dataCompiler_1.tidyArgs)(rawArgs).uris));
+    const links = [];
+    for (const { table, column } of fileColumns(schema)) {
+        const rows = Number(first(runner, `SELECT count(*) AS n FROM ${(0, dataIdentifiers_1.quoteIdentifier)(table.name)} WHERE ${(0, dataIdentifiers_1.quoteIdentifier)(column.name)} IN (SELECT value FROM json_each(?))`, [uris])?.n ?? 0);
+        if (rows === 0)
+            continue;
+        links.push({
+            table: table.name,
+            tableLabel: table.label,
+            column: column.name,
+            columnLabel: column.label,
+            required: column.required,
+            rows
+        });
+    }
+    return { links };
+};
+exports.fileLinks = fileLinks;
+// Points the links at `from` to `to`, or clears them (`to: null`) once the
+// item is gone. A required column keeps its link, which then reads as
+// missing. Recorded in row history; triggers don't see it.
+const replaceFileLinks = (runner, schema, caller, rawArgs) => {
+    (0, exports.assertActor)(caller);
+    if (caller.restricted) {
+        throw new dataTypes_1.DataError('File links are for the owner.', 'forbidden');
+    }
+    const raw = (0, dataCompiler_1.tidyArgs)(rawArgs).changes;
+    if (!Array.isArray(raw) ||
+        raw.length === 0 ||
+        raw.length > dataTypes_1.DATA_FILE_LINKS_MAX_URIS) {
+        throw new dataTypes_1.DataError(`"changes" lists 1 to ${dataTypes_1.DATA_FILE_LINKS_MAX_URIS} { from, to } pairs.`);
+    }
+    const changes = raw.map(change => {
+        if (!isPlainObject(change)) {
+            throw new dataTypes_1.DataError('Each change is { from, to }; to is null to clear.');
+        }
+        return {
+            from: (0, dataCompiler_1.fileUriOf)(change.from, 'from'),
+            to: change.to === null ? null : (0, dataCompiler_1.fileUriOf)(change.to, 'to')
+        };
+    });
+    const columns = fileColumns(schema);
+    if (columns.length === 0)
+        return { updated: 0, kept: [] };
+    (0, exports.assertWritable)(runner, caller, changes.some(change => change.to !== null));
+    return runner.transaction(() => {
+        setContextActor(runner, caller.actor);
+        runner.all('DELETE FROM _ganju_changes');
+        let updated = 0;
+        const kept = [];
+        for (const { table, column } of columns) {
+            for (const change of changes) {
+                if (change.to === null && column.required) {
+                    const rows = Number(first(runner, `SELECT count(*) AS n FROM ${(0, dataIdentifiers_1.quoteIdentifier)(table.name)} WHERE ${(0, dataIdentifiers_1.quoteIdentifier)(column.name)} = ?`, [change.from])?.n ?? 0);
+                    if (rows > 0)
+                        kept.push({ table: table.name, column: column.name, rows });
+                    continue;
+                }
+                updated += runner.all(`UPDATE ${(0, dataIdentifiers_1.quoteIdentifier)(table.name)} SET ${(0, dataIdentifiers_1.quoteIdentifier)(column.name)} = ?, version = version + 1, updated_at = ${dataDdl_1.DATA_NOW_SQL}, updated_by = ? WHERE ${(0, dataIdentifiers_1.quoteIdentifier)(column.name)} = ? RETURNING id`, [change.to, caller.actor, change.from]).length;
+            }
+        }
+        // Tidying links after a knowledge change isn't the owner's edit: it
+        // stays in row history but fires no trigger.
+        runner.all('DELETE FROM _ganju_changes');
+        return { updated, kept };
+    });
+};
+exports.replaceFileLinks = replaceFileLinks;
 // Row history
 const rowHistory = (runner, schema, caller, args) => {
     const table = (0, dataCompiler_1.tableFor)(schema, caller, args.table);

package/dist/dataIndexAdvice.d.ts

@@ -0,0 +1,36 @@
+import type { DataSchema } from './dataTypes';
+export interface IndexAdviceStat {
+    tableName: string;
+    columnName: string;
+    queries: number;
+    rowsRead: number;
+    rowsReturned: number;
+    rowsWritten: number;
+}
+export interface IndexAdviceCandidate {
+    tableName: string;
+    columnName: string;
+    kind: 'add' | 'unused';
+    queries: number;
+    avgRowsRead: number;
+    avgRowsReturned: number;
+    rowsWritten: number;
+}
+export interface IndexAdviceInput {
+    schema: DataSchema;
+    week: IndexAdviceStat[];
+    month: IndexAdviceStat[];
+    monthCovered: boolean;
+    recentlyIndexed: Set<string>;
+}
+export declare const adviseIndexes: (input: IndexAdviceInput) => IndexAdviceCandidate[];
+export declare const adviceDoubled: (current: {
+    queries: number;
+    avgRowsRead: number;
+    rowsWritten: number;
+}, dismissed: {
+    queries: number | null;
+    avgRowsRead: number | null;
+    rowsWritten: number | null;
+}) => boolean;
+//# sourceMappingURL=dataIndexAdvice.d.ts.map

package/dist/dataIndexAdvice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataIndexAdvice.d.ts","sourceRoot":"","sources":["../src/dataIndexAdvice.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAG9C,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,KAAK,GAAG,QAAQ,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,UAAU,CAAC;IAEnB,IAAI,EAAE,eAAe,EAAE,CAAC;IACxB,KAAK,EAAE,eAAe,EAAE,CAAC;IAEzB,YAAY,EAAE,OAAO,CAAC;IAEtB,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC9B;AAMD,eAAO,MAAM,aAAa,GACxB,OAAO,gBAAgB,KACtB,oBAAoB,EA+DtB,CAAC;AAGF,eAAO,MAAM,aAAa,GACxB,SAAS;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,EACtE,WAAW;IACT,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B,KACA,OASkD,CAAC"}

package/dist/dataIndexAdvice.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.adviceDoubled = exports.adviseIndexes = void 0;
+// Which columns of a database are worth an index, and which indexes nobody
+// uses, from the API's daily query stats and the database's schema. Pure, so
+// the daily job and the tests apply the same rule.
+const constants_1 = require("./constants");
+const dataDdl_1 = require("./dataDdl");
+// Indexes the owner can add or remove: a column marked filterable. Unique and
+// relation columns are indexed for what they are, and stay.
+const canIndex = (type) => type !== 'json' && type !== 'long_text';
+const adviseIndexes = (input) => {
+    const out = [];
+    const tables = new Map(input.schema.tables.map(t => [t.name, t]));
+    for (const stat of input.week) {
+        if (!stat.columnName)
+            continue;
+        const table = tables.get(stat.tableName);
+        const column = table?.columns.find(c => c.name === stat.columnName);
+        if (!column || (0, dataDdl_1.isIndexedColumn)(column) || !canIndex(column.type))
+            continue;
+        if (stat.queries < constants_1.constants.DATA_INDEX_ADVICE_MIN_QUERIES)
+            continue;
+        const avgRead = stat.rowsRead / stat.queries;
+        const avgReturned = stat.rowsReturned / stat.queries;
+        if (avgRead < constants_1.constants.DATA_INDEX_ADVICE_MIN_ROWS_READ)
+            continue;
+        // Scanning, not just a small table: many rows read for each one returned.
+        if (stat.rowsRead <
+            constants_1.constants.DATA_INDEX_ADVICE_MIN_READ_RATIO * stat.rowsReturned) {
+            continue;
+        }
+        out.push({
+            tableName: stat.tableName,
+            columnName: stat.columnName,
+            kind: constants_1.constants.DATA_INDEX_ADVICE_ADD,
+            queries: stat.queries,
+            avgRowsRead: Math.round(avgRead),
+            avgRowsReturned: Math.round(avgReturned),
+            rowsWritten: 0
+        });
+    }
+    if (input.monthCovered) {
+        const used = new Set(input.month
+            .filter(s => s.columnName && s.queries > 0)
+            .map(s => `${s.tableName}.${s.columnName}`));
+        for (const table of input.schema.tables) {
+            const totals = input.month.find(s => s.tableName === table.name && s.columnName === '');
+            const written = totals?.rowsWritten ?? 0;
+            if (written < constants_1.constants.DATA_INDEX_UNUSED_MIN_ROWS_WRITTEN)
+                continue;
+            if (written <= (totals?.queries ?? 0))
+                continue;
+            if (input.recentlyIndexed.has(table.name))
+                continue;
+            for (const column of table.columns) {
+                if (!column.filterable || column.unique)
+                    continue;
+                if (column.type === 'relation' || column.type === 'file')
+                    continue;
+                const key = `${table.name}.${column.name}`;
+                if (used.has(key) || input.recentlyIndexed.has(key))
+                    continue;
+                out.push({
+                    tableName: table.name,
+                    columnName: column.name,
+                    kind: constants_1.constants.DATA_INDEX_ADVICE_UNUSED,
+                    queries: 0,
+                    avgRowsRead: 0,
+                    avgRowsReturned: 0,
+                    rowsWritten: written
+                });
+            }
+        }
+    }
+    return out;
+};
+exports.adviseIndexes = adviseIndexes;
+// A dismissed suggestion comes back once its numbers have doubled.
+const adviceDoubled = (current, dismissed) => (dismissed.queries !== null &&
+    dismissed.queries > 0 &&
+    current.queries >= 2 * dismissed.queries) ||
+    (dismissed.avgRowsRead !== null &&
+        dismissed.avgRowsRead > 0 &&
+        current.avgRowsRead >= 2 * dismissed.avgRowsRead) ||
+    (dismissed.rowsWritten !== null &&
+        dismissed.rowsWritten > 0 &&
+        current.rowsWritten >= 2 * dismissed.rowsWritten);
+exports.adviceDoubled = adviceDoubled;

package/dist/dataRpc.d.ts

@@ -1,4 +1,4 @@
-import type { DataCaller, DataDeleteImpact, DataResult, DataSchema, DataTable, DataTableCopy } from './dataTypes';
+import type { DataCaller, DataDeleteImpact, DataFileLinkChange, DataFileLinks, DataFileLinksReplaced, DataResult, DataSchema, DataTable, DataTableCopy } from './dataTypes';
 import type { DataQuery } from './dataQueries';
 import type { DataTrigger, DataTriggerWithSecret, SavedTrigger } from './dataTriggers';
 export type ExportFormat = 'jsonl' | 'csv';
@@ -45,6 +45,7 @@ export interface DatabaseInfo {
         name: string;
         label: string | null;
         columns: number;
+        rows: number;
     }[];
     copy: DataTableCopy | null;
 }
@@ -109,6 +110,10 @@ export interface ProjectDatabaseRpc {
     }>;
     describe(caller: DataCaller, args?: unknown): R<unknown>;
     query(caller: DataCaller, args: unknown): R<unknown>;
+    eventRow(caller: DataCaller, args: {
+        table: string;
+        id?: number;
+    }): R<Record<string, unknown> | null>;
     write(caller: DataCaller, args: unknown): R<{
         ok: true;
         results: unknown[];
@@ -117,6 +122,12 @@ export interface ProjectDatabaseRpc {
         table: string;
         ids?: number[];
     }): R<DataDeleteImpact>;
+    fileLinks(caller: DataCaller, args: {
+        uris: string[];
+    }): R<DataFileLinks>;
+    replaceFileLinks(caller: DataCaller, args: {
+        changes: DataFileLinkChange[];
+    }): R<DataFileLinksReplaced>;
     history(caller: DataCaller, args: {
         table: string;
         id: number;

package/dist/dataRpc.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dataRpc.d.ts","sourceRoot":"","sources":["../src/dataRpc.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dataRpc.d.ts","sourceRoot":"","sources":["../src/dataRpc.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,UAAU,EACV,gBAAgB,EAChB,kBAAkB,EAClB,aAAa,EACb,qBAAqB,EACrB,UAAU,EACV,UAAU,EACV,SAAS,EACT,aAAa,EACd,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEvF,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,KAAK,CAAC;AAE3C,MAAM,WAAW,UAAU;IAEzB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,SAAS,GAAG,MAAM,GAAG,QAAQ,CAAC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE;QACN,GAAG,EAAE,MAAM,CAAC;QACZ,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE;YAAE,UAAU,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,EAAE,CAAC;QAC9C,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;QAGd,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;KACzB,GAAG,IAAI,CAAC;IACT,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAE5B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IAEb,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAGhF,IAAI,EAAE,aAAa,GAAG,IAAI,CAAC;CAC5B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,KAAK,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;AAEnC,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,IAAI,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,CAAC,CAAC,YAAY,CAAC,CAAC;IAClE,IAAI,IAAI,CAAC,CAAC,YAAY,CAAC,CAAC;IACxB,MAAM,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,CAAC,CAAC,YAAY,CAAC,CAAC;IAChD,IAAI,IAAI,CAAC,CAAC;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7B,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,CAAC,CAAC,YAAY,CAAC,CAAC;IACpF,WAAW,CACT,MAAM,EAAE,UAAU,GACjB,CAAC,CAAC;QAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrD,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,CAAC,CAAC,YAAY,CAAC,CAAC;IAC9C,KAAK,IAAI,CAAC,CAAC;QAAE,MAAM,EAAE,IAAI,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,eAAe,IAAI,CAAC,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC3C,SAAS,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,CAAC,CAAC,aAAa,CAAC,CAAC;IAC7E,iBAAiB,CAAC,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,CAAC,CAAC,aAAa,CAAC,CAAC;IAChE,UAAU,IAAI,CAAC,CAAC,UAAU,CAAC,CAAC;IAC5B,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC;IAC9D,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC;IAC7E,SAAS,CACP,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,MAAM,GACZ,CAAC,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC5C,SAAS,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC;IAC3E,YAAY,CACV,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,GACb,CAAC,CAAC;QAAE,KAAK,EAAE,SAAS,CAAC;QAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,IAAI,EAAE,aAAa,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;IAChF,UAAU,CACR,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb,CAAC,CAAC;QAAE,KAAK,EAAE,SAAS,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,aAAa,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;IAEzE,WAAW,CAAC,MAAM,EAAE,UAAU,GAAG,CAAC,CAAC;QAAE,IAAI,EAAE,IAAI,CAAA;KAAE,CAAC,CAAC;IACnD,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC;IACzD,KAAK,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC;IAGrD,QAAQ,CACN,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,GACnC,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;IACrC,KAAK,CACH,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,OAAO,GACZ,CAAC,CAAC;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,OAAO,EAAE,OAAO,EAAE,CAAA;KAAE,CAAC,CAAC;IACvC,YAAY,CACV,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GACtC,CAAC,CAAC,gBAAgB,CAAC,CAAC;IAEvB,SAAS,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,CAAC,CAAC,aAAa,CAAC,CAAC;IAC1E,gBAAgB,CACd,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE;QAAE,OAAO,EAAE,kBAAkB,EAAE,CAAA;KAAE,GACtC,CAAC,CAAC,qBAAqB,CAAC,CAAC;IAC5B,OAAO,CACL,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GACnE,CAAC,CAAC,OAAO,CAAC,CAAC;IACd,WAAW,CAAC,MAAM,EAAE,UAAU,GAAG,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC;IAChD,SAAS,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC;IAC5D,SAAS,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpE,QAAQ,CACN,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GACvE,CAAC,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAE7E,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,CAAC,CAAC;QAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClF,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,CAAC,CAAC,qBAAqB,CAAC,CAAC;IACvD,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,GAAG,CAAC,CAAC,YAAY,CAAC,CAAC;IACjE,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtE,iBAAiB,CACf,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAC/D,CAAC,CAAC,WAAW,CAAC,CAAC;IAClB,sBAAsB,CACpB,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,OAAO,GACd,CAAC,CAAC;QAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,CAAC,CAAC;IACtF,WAAW,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,CAAC,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC9D,WAAW,CACT,MAAM,EAAE,UAAU,EAClB,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,YAAY,CAAA;KAAE,GAC/B,CAAC,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAA;KAAE,CAAC,CAAC;IAC1D,YAAY,CAAC,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC;CAC5D"}

package/dist/dataTools.js

@@ -39,7 +39,7 @@ const CHANGES = {
     destructiveHint: true,
     openWorldHint: false
 };
-const WHERE_HELP = 'Filter object. { "column": value } matches exactly; { "column": { "op": value } } with op one of eq, ne, gt, gte, lt, lte, in, notIn (lists), contains, startsWith (text, case-insensitive), isNull (true/false). Several keys must all match; { "or": [ {...}, {...} ] } matches any. A relation column takes the related row\'s id, or filter on a column of the related table with "relation.column", e.g. { "product.name": "Margherita" }. Datetimes are ISO 8601; include the offset for local times, e.g. "2026-10-19T00:00:00-05:00".';
+const WHERE_HELP = 'Filter object. { "column": value } matches exactly; { "column": { "op": value } } with op one of eq, ne, gt, gte, lt, lte, in, notIn (lists), contains, startsWith (text, case-insensitive), isNull (true/false). Several keys must all match; { "or": [ {...}, {...} ] } matches any. A relation column takes the related row\'s id, or filter on a column of the related table with "relation.column", e.g. { "product.name": "Margherita" }. A file column matches the item\'s uri. Datetimes are ISO 8601; include the offset for local times, e.g. "2026-10-19T00:00:00-05:00".';
 const accessOf = (caller, table) => caller.restricted ? table.access : 'full';
 const visible = (schema, caller) => schema.tables.filter(table => dataTypes_1.DATA_ACCESS_RANK[accessOf(caller, table)] >= 1);
 // One column as data-query's description lists it: the type when it isn't
@@ -100,7 +100,7 @@ const dataToolDefinitions = (schema, caller, options = {}) => {
             title: exports.DATA_TOOL_TITLES[exports.DATA_TOOL_QUERY],
             description: [
                 "Read rows from the project's database: structured records such as products, prices, stock, orders, bookings or customers. Use it for anything with fields and numbers; use the knowledge/resource tools for documents and pages.",
-                'Returns matching rows (relation columns come back as { id, label }), the total that match, and nextCursor when there are more. With "aggregate" it returns counts, sums, averages, minimums or maximums instead of rows, optionally per group: use that for "how many" and "how much" rather than adding rows up yourself.',
+                'Returns matching rows (relation columns come back as { id, label }; file columns as { uri, title, mimeType }, or { uri, missing: true } when the item is gone: deliver one with send-resource and its uri, or read a document with read-resource), the total that match, and nextCursor when there are more. With "aggregate" it returns counts, sums, averages, minimums or maximums instead of rows, optionally per group: use that for "how many" and "how much" rather than adding rows up yourself.',
                 "The database holds only what these tables and columns hold. When a question needs something they don't have (opening hours, parking, calories, reviews, forecasts), look in the knowledge tools if you have them; if nothing has it, say you don't have that information. Never guess it.",
                 `Every table also has id, created_at and updated_at. Datetimes come back in the project's time zone (${timeZone}) with their offset; read them as local times.`,
                 'Tables:',
@@ -185,7 +185,7 @@ const dataToolDefinitions = (schema, caller, options = {}) => {
             title: exports.DATA_TOOL_TITLES[exports.DATA_TOOL_WRITE],
             description: [
                 "Add, change or delete rows in the project's database. All operations in one call succeed together or none is applied, so put everything that belongs together (an order, its lines and the stock they use) in one call.",
-                '- insert: { "op": "insert", "table": "...", "values": { column: value } }. A relation column takes the related row\'s id; to point at a row inserted earlier in the same call use { "$ref": n }, n being that operation\'s position (0-based).',
+                '- insert: { "op": "insert", "table": "...", "values": { column: value } }. A relation column takes the related row\'s id; to point at a row inserted earlier in the same call use { "$ref": n }, n being that operation\'s position (0-based). A file column takes the uri of an item in the project\'s knowledge (from list-resources or search-resources), or null.',
                 '- update: { "op": "update", "table": "...", "id": 12, "set": { column: value } }. For numbers, { "decrement": 2 } or { "increment": 2 } changes the value relative to what is stored. Instead of id you can give "where" (same format as data-query).',
                 '- delete: { "op": "delete", "table": "...", "id": 12 } (or "where").',
                 'Guards: an update or delete also takes "where" conditions that must hold, e.g. "where": { "stock": { "gte": 2 } }, and "expect", how many rows must change (1 by default when id is given). If a guard fails, nothing in the call is written and the error says why (e.g. how much stock is left).',