fix(agent-bff): derive a primary key when the schema declares none

Author: Tonours

packages/agent-bff/src/context/build-context.ts

@@ -113,6 +113,7 @@ function toContextValidations(validations: unknown[] | null | undefined): Contex
 function toContextField(
   field: FieldWithWireEnums,
   ambiguousKeys: ReadonlySet<string>,
+  derivedPrimaryKeys: ReadonlySet<string>,
 ): ContextField {
   const serialized: ContextField = { field: field.field, type: field.type };
 
@@ -126,7 +127,10 @@ function toContextField(
   const polymorphicTargets = toArray(field.polymorphicReferencedModels);
   if (polymorphicTargets.length > 0) serialized.polymorphicTargets = [...polymorphicTargets];
 
-  if (field.isPrimaryKey) serialized.isPrimaryKey = true;
+  // The read-model derives a key when the schema declares none, and the BFF builds record
+  // identifiers from it. Publishing only the schema's flag would leave a client unable to name the
+  // key the BFF is actually using.
+  if (field.isPrimaryKey || derivedPrimaryKeys.has(field.field)) serialized.isPrimaryKey = true;
   if (field.isRequired) serialized.isRequired = true;
   if (field.isReadOnly) serialized.isReadOnly = true;
 
@@ -168,10 +172,13 @@ function toContextCollection(
     field => typeof field === 'object' && field !== null,
   );
   const ambiguousKeys = ambiguousRecordKeys(fields);
+  const derivedPrimaryKeys = new Set(
+    readModel.getPrimaryKeys(collection.name).map(key => key.name),
+  );
 
   return {
     name: collection.name,
-    fields: fields.map(field => toContextField(field, ambiguousKeys)),
+    fields: fields.map(field => toContextField(field, ambiguousKeys, derivedPrimaryKeys)),
     actions: toArray(collection.actions)
       .filter(action => {
         const allowed = allowedActions[action?.name];

packages/agent-bff/src/read-model/read-model.ts

@@ -131,13 +131,33 @@ export default class ReadModel {
     }
   }
 
+  /**
+   * A schema that declares no primary key at all gets one derived from its `id` field.
+   *
+   * `forest_liana` only started publishing `isPrimaryKey` in 9.17.6 (2026-06-04), and an older one
+   * leaves every collection without a key — which makes `unpackPrimaryKey` reject every record the
+   * agent returns, so a plain list answers `500 mapping_error`. The record id is there regardless:
+   * the agent serialises it as the JSON:API `id`, and 257 of the 269 collections in the schema this
+   * was measured against carry a field literally named `id`.
+   *
+   * Keyed on the shape of the schema, not on the liana: a collection that declares a key keeps it,
+   * and every v2 agent declares one, so this only fires where the alternative is a 500. `String`
+   * when no `id` field is declared, because the packed id survives a string round-trip untouched
+   * while a wrong numeric cast would not.
+   */
   private buildPrimaryKeys(collection: ForestSchemaCollection): void {
     const keys: PrimaryKeyField[] = [];
 
     for (const field of collection.fields ?? []) {
       if (field.isPrimaryKey) keys.push({ name: field.field, type: field.type });
     }
 
+    if (keys.length === 0) {
+      const declaredId = (collection.fields ?? []).find(field => field.field === 'id');
+
+      keys.push({ name: 'id', type: declaredId?.type ?? 'String' });
+    }
+
     this.primaryKeys.set(collection.name, keys);
   }
 

packages/agent-bff/test/read-model/read-model.test.ts

@@ -313,5 +313,37 @@ describe('ReadModel', () => {
 
       expect(model.getPrimaryKeys('ghost')).toEqual([]);
     });
+
+    // A forest_liana older than 9.17.6 publishes no isPrimaryKey anywhere, which used to leave the
+    // collection keyless and make every list answer 500 mapping_error.
+    describe('when the schema declares no key', () => {
+      it('should fall back to the id field with the type the schema gives it', () => {
+        const model = new ReadModel([
+          collection('users', [
+            { ...column('id'), type: 'Number', isPrimaryKey: false },
+            column('email'),
+          ]),
+        ]);
+
+        expect(model.getPrimaryKeys('users')).toEqual([{ name: 'id', type: 'Number' }]);
+      });
+
+      it('should fall back to a string id when the schema declares no id field either', () => {
+        const model = new ReadModel([collection('audits', [column('label')])]);
+
+        expect(model.getPrimaryKeys('audits')).toEqual([{ name: 'id', type: 'String' }]);
+      });
+
+      it('should leave a declared key alone, so a v2 agent is untouched', () => {
+        const model = new ReadModel([
+          collection('users', [
+            { ...column('reference'), type: 'String', isPrimaryKey: true },
+            { ...column('id'), type: 'Number', isPrimaryKey: false },
+          ]),
+        ]);
+
+        expect(model.getPrimaryKeys('users')).toEqual([{ name: 'reference', type: 'String' }]);
+      });
+    });
   });
 });