@jskit-ai/crud-core 0.1.177 → 0.1.179

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/crud-core",
-  "version": "0.1.177",
+  "version": "0.1.179",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -23,11 +23,9 @@
     "./server/routeContracts": "./src/server/routeContracts.js"
   },
   "dependencies": {
-    "@jskit-ai/database-runtime": "0.1.166",
-    "@jskit-ai/http-runtime": "0.1.164",
-    "@jskit-ai/json-rest-api-core": "0.1.110",
-    "@jskit-ai/kernel": "0.1.166",
-    "@jskit-ai/resource-crud-core": "0.1.108",
+    "@jskit-ai/database-runtime": "0.1.168",
+    "@jskit-ai/json-rest-api-core": "0.1.112",
+    "@jskit-ai/resource-crud-core": "0.1.110",
     "json-rest-schema": "^1.0.17"
   },
   "description": "Shared server-side CRUD service, repository, route, and query helpers.",
@@ -45,5 +43,9 @@
         "providers": []
       }
     }
+  },
+  "peerDependencies": {
+    "@jskit-ai/http-runtime": "0.1.166",
+    "@jskit-ai/kernel": "0.1.168"
   }
 }

package/patterns/json-api-resource-package/example/packages/books/package.json

@@ -8,8 +8,8 @@
     "./shared": "./src/shared/index.js"
   },
   "dependencies": {
-    "@jskit-ai/crud-core": "0.1.177",
-    "@jskit-ai/resource-crud-core": "0.1.108"
+    "@jskit-ai/crud-core": "0.1.179",
+    "@jskit-ai/resource-crud-core": "0.1.110"
   },
   "jskit": {
     "kind": "runtime",

package/src/server/jsonApiModule/actions.js

@@ -1,9 +1,16 @@
 import {
   composeSchemaDefinitions,
+  createSchema,
   recordIdParamsValidator
 } from "@jskit-ai/kernel/shared/validators";
 import { createEntityChangedActionEvent } from "@jskit-ai/kernel/server/actions";
+import {
+  decodeJsonApiResourceResponse,
+  normalizeJsonApiDocument,
+  unwrapJsonApiResult
+} from "@jskit-ai/http-runtime/shared";
 import { resolveCrudRecordChangedEvent } from "@jskit-ai/resource-crud-core/shared/crudNamespaceSupport";
+import { resolveJsonApiRelationshipEntries } from "../routeContracts.js";
 import {
   createStandardCrudListQueryValidators,
   createStandardCrudViewQueryValidators
@@ -12,6 +19,255 @@ import {
 const CRUD_OPERATION_NAMES = Object.freeze(["list", "view", "create", "update", "delete"]);
 const CRUD_MUTATION_NAMES = new Set(["create", "update", "delete"]);
 const CRUD_LIFECYCLE_PHASES = Object.freeze(["before", "execute", "after", "afterCommit"]);
+const CRUD_ASSISTANT_RESOURCE_OPERATION = Object.freeze({
+  list: "list",
+  view: "view",
+  create: "create",
+  update: "patch",
+  delete: "delete"
+});
+
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function normalizeOptionalCursor(value) {
+  if (value == null) {
+    return null;
+  }
+  const normalized = String(value).trim();
+  return normalized || null;
+}
+
+function resolveAssistantResultValue(result) {
+  const taggedResult = unwrapJsonApiResult(result);
+  const value = taggedResult ? taggedResult.value : result;
+  const document = normalizeJsonApiDocument(value);
+  return {
+    value,
+    document
+  };
+}
+
+function resolveSchemaFieldDefinitions(definition = null) {
+  const definitions = definition?.schema?.getFieldDefinitions?.();
+  return isRecord(definitions) ? definitions : {};
+}
+
+function createProjectionRecordSchema(recordSchema, {
+  lookupContainerKey = "",
+  relationshipEntries = []
+} = {}) {
+  const definitions = recordSchema?.getFieldDefinitions?.();
+  if (!isRecord(definitions)) {
+    return recordSchema;
+  }
+
+  const fields = Object.fromEntries(
+    Object.entries(definitions).map(([fieldKey, fieldDefinition]) => [
+      fieldKey,
+      {
+        ...fieldDefinition,
+        required: fieldKey === "id" && fieldDefinition?.required === true
+      }
+    ])
+  );
+  if (lookupContainerKey && isRecord(fields[lookupContainerKey])) {
+    const createRelatedRecordSchema = (entry) => createSchema({
+      id: {
+        type: "string",
+        required: true
+      },
+      ...(entry.labelKey && entry.labelKey !== "id"
+        ? {
+            [entry.labelKey]: {
+              type: "string",
+              required: false,
+              nullable: true
+            }
+          }
+        : {})
+    });
+    const lookupFields = Object.fromEntries(
+      relationshipEntries.map((entry) => [
+        entry.relationshipName,
+        entry.many === true
+          ? {
+              type: "array",
+              required: false,
+              items: {
+                type: "object",
+                schema: createRelatedRecordSchema(entry),
+                additionalProperties: true
+              }
+            }
+          : {
+              type: "object",
+              required: false,
+              schema: createRelatedRecordSchema(entry),
+              additionalProperties: true
+            }
+      ])
+    );
+    fields[lookupContainerKey] = {
+      ...fields[lookupContainerKey],
+      type: "object",
+      required: false,
+      ...(Object.keys(lookupFields).length > 0 ? { schema: createSchema(lookupFields) } : {}),
+      additionalProperties: true
+    };
+  }
+
+  return createSchema(fields);
+}
+
+function createProjectionOutputDefinition(output, operation, relationshipEntries, lookupContainerKey) {
+  if (!output || (operation !== "list" && operation !== "view")) {
+    return output;
+  }
+
+  if (operation === "view") {
+    return Object.freeze({
+      schema: createProjectionRecordSchema(output.schema, { lookupContainerKey, relationshipEntries }),
+      mode: "replace"
+    });
+  }
+
+  const listFields = resolveSchemaFieldDefinitions(output);
+  const items = listFields.items;
+  if (!isRecord(items) || items.type !== "array" || typeof items.items?.getFieldDefinitions !== "function") {
+    return output;
+  }
+
+  return Object.freeze({
+    schema: createSchema({
+      ...listFields,
+      items: {
+        ...items,
+        items: createProjectionRecordSchema(items.items, { lookupContainerKey, relationshipEntries })
+      }
+    }),
+    mode: "replace"
+  });
+}
+
+function createCrudAssistantTransport(resource, operation, relationshipEntries, lookupContainerKey) {
+  const lookupFieldMap = Object.fromEntries(
+    relationshipEntries
+      .filter((entry) => entry.many !== true)
+      .map((entry) => [entry.relationshipName, entry.attributeKey])
+  );
+  return Object.freeze({
+    kind: "jsonapi-resource",
+    responseType: resource.namespace,
+    responseKind: operation === "list" ? "collection" : "record",
+    ...(lookupContainerKey ? { lookupContainerKey } : {}),
+    ...(Object.keys(lookupFieldMap).length > 0 ? { lookupFieldMap } : {})
+  });
+}
+
+function transformCrudAssistantResult(operation, result, {
+  input = {},
+  resource,
+  relationshipEntries = [],
+  lookupContainerKey = ""
+} = {}) {
+  if (operation === "delete") {
+    const resolved = resolveAssistantResultValue(result);
+    if (isRecord(resolved.value) && resolved.value.deleted === true && resolved.value.id != null) {
+      return resolved.value;
+    }
+    return {
+      id: String(input.recordId || ""),
+      deleted: true
+    };
+  }
+
+  const resolved = resolveAssistantResultValue(result);
+  if (operation === "list") {
+    if (resolved.document.kind === "collection") {
+      const decoded = decodeJsonApiResourceResponse(
+        resolved.value,
+        createCrudAssistantTransport(resource, operation, relationshipEntries, lookupContainerKey)
+      );
+      return {
+        items: decoded.items,
+        nextCursor: normalizeOptionalCursor(decoded.nextCursor)
+      };
+    }
+    if (Array.isArray(resolved.value)) {
+      return {
+        items: resolved.value,
+        nextCursor: null
+      };
+    }
+    if (isRecord(resolved.value) && Array.isArray(resolved.value.items)) {
+      return {
+        items: resolved.value.items,
+        nextCursor: normalizeOptionalCursor(resolved.value.nextCursor)
+      };
+    }
+    return resolved.value;
+  }
+
+  if (resolved.document.kind === "resource") {
+    return decodeJsonApiResourceResponse(
+      resolved.value,
+      createCrudAssistantTransport(resource, operation, relationshipEntries, lookupContainerKey)
+    );
+  }
+  return resolved.value;
+}
+
+function createCrudAssistantExtension(resource, namespace, operation) {
+  const resourceOperation = CRUD_ASSISTANT_RESOURCE_OPERATION[operation];
+  const nativeOutput = resource?.operations?.[resourceOperation]?.output || null;
+  const recordOutput = operation === "list"
+    ? Object.freeze({
+        schema: resolveSchemaFieldDefinitions(nativeOutput).items?.items,
+        mode: "replace"
+      })
+    : nativeOutput;
+  const relationshipEntries = resolveJsonApiRelationshipEntries(recordOutput);
+  const lookupContainerKey = String(resource?.contract?.lookup?.containerKey || "").trim();
+  const output = createProjectionOutputDefinition(
+    nativeOutput,
+    operation,
+    relationshipEntries,
+    lookupContainerKey
+  );
+  const firstRelationship = relationshipEntries[0] || null;
+  const fieldsExample = firstRelationship
+    ? ` fields can be {\"${namespace}\":[\"${firstRelationship.attributeKey}\"],` +
+      `\"${firstRelationship.relationshipType}\":[\"${firstRelationship.labelKey || "id"}\"]}.`
+    : ` fields can be {\"${namespace}\":[\"id\"]}.`;
+  const lookupExample = firstRelationship && lookupContainerKey
+    ? ` Included fields are returned under ${operation === "list" ? "items[]." : ""}${lookupContainerKey}.` +
+      `${firstRelationship.relationshipName}.${firstRelationship.labelKey || "<selectedField>"}.`
+    : "";
+  const actionLabel = operation === "list"
+    ? `List ${namespace} records. include must be a comma-separated string such as \"pet,service\";${fieldsExample}${lookupExample}`
+    : operation === "view"
+      ? `View a ${namespace} record. include must be a comma-separated string such as \"pet,service\";${fieldsExample}${lookupExample}`
+      : operation === "create"
+        ? `Create a ${namespace} record.`
+        : operation === "update"
+          ? `Update a ${namespace} record.`
+          : `Delete a ${namespace} record.`;
+
+  return Object.freeze({
+    description: actionLabel,
+    output,
+    transformResult(result, context) {
+      return transformCrudAssistantResult(operation, result, {
+        ...context,
+        resource,
+        relationshipEntries,
+        lookupContainerKey
+      });
+    }
+  });
+}
 
 function createActionInput(
   resource,
@@ -303,6 +559,9 @@ function createCrudJsonApiActions({
       permission: permission(definition.operation),
       input: input(definition.operation),
       output: null,
+      extensions: Object.freeze({
+        assistant: createCrudAssistantExtension(resource, namespace, definition.operation)
+      }),
       idempotency: definition.idempotency,
       audit: { actionName: id },
       observability: {},

package/src/server/listQueryValidators.js

@@ -19,7 +19,10 @@ const lookupIncludeQueryValidator = Object.freeze({
   schema: createSchema({
     include: {
       type: "string",
-      required: false
+      required: false,
+      messages: {
+        default: "include expects a comma-separated string such as \"pet,service\"."
+      }
     }
   }),
   mode: "patch"
@@ -30,6 +33,9 @@ const jsonApiFieldsetsQueryValidator = Object.freeze({
     fields: {
       type: "object",
       required: false,
+      messages: {
+        default: "fields expects an object such as {\"bookings\":[\"petId\"],\"pets\":[\"name\"]}."
+      },
       values: {
         type: "array",
         items: {

package/src/server/routeContracts.js

@@ -44,6 +44,7 @@ function resolveJsonApiRelationshipEntries(definition = null) {
         attributeKey: fieldKey,
         relationshipName,
         relationshipType,
+        labelKey: String(normalizedFieldDefinition?.relation?.labelKey || "").trim(),
         required: normalizedFieldDefinition.required === true,
         nullable: normalizedFieldDefinition.nullable === true
       }));
@@ -75,6 +76,7 @@ function resolveJsonApiRelationshipEntries(definition = null) {
       attributeKey: fieldKey,
       relationshipName: collectionRelationshipName,
       relationshipType: collectionRelationshipType,
+      labelKey: String(relation.labelKey || "").trim(),
       many: true,
       required: normalizedFieldDefinition.required === true,
       nullable: normalizedFieldDefinition.nullable === true
@@ -574,4 +576,4 @@ function createCrudJsonApiRouteContracts({
   });
 }
 
-export { createCrudJsonApiRouteContracts };
+export { createCrudJsonApiRouteContracts, resolveJsonApiRelationshipEntries };

package/test/assistantActionConformance.test.js

@@ -0,0 +1,344 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createServiceToolCatalog } from "@jskit-ai/assistant-core/server";
+import { createActionCatalogue } from "@jskit-ai/kernel/server/actions";
+import {
+  createSchema,
+  validateSchemaPayload
+} from "@jskit-ai/kernel/shared/validators";
+import { returnJsonApiDocument } from "@jskit-ai/http-runtime/shared";
+import { defineCrudResource } from "@jskit-ai/resource-crud-core/shared/crudResource";
+import { createCrudJsonApiActions } from "../src/server/jsonApiModule/actions.js";
+
+const BOOKINGS = Object.freeze([
+  Object.freeze({ id: "41", petId: "7", summary: "Wash and trim" }),
+  Object.freeze({ id: "42", petId: "8", summary: "Nail trim" })
+]);
+const PETS = Object.freeze({
+  "7": Object.freeze({ id: "7", name: "Fido", species: "dog" }),
+  "8": Object.freeze({ id: "8", name: "Mabel", species: "cat" })
+});
+
+function createBookingsResource() {
+  return defineCrudResource({
+    namespace: "bookings",
+    tableName: "bookings",
+    crudOperations: ["list", "view"],
+    contract: {
+      lookup: {
+        containerKey: "lookups"
+      }
+    },
+    schema: {
+      petId: {
+        type: "id",
+        required: true,
+        belongsTo: "pets",
+        as: "pet",
+        relation: {
+          kind: "lookup",
+          namespace: "pets",
+          valueKey: "id",
+          labelKey: "name"
+        },
+        operations: {
+          output: { required: true }
+        }
+      },
+      summary: {
+        type: "string",
+        required: true,
+        operations: {
+          output: { required: true }
+        }
+      }
+    }
+  });
+}
+
+function selectFields(source, selectedFields = null) {
+  if (!Array.isArray(selectedFields)) {
+    return { ...source };
+  }
+  return Object.fromEntries(
+    selectedFields
+      .filter((field) => Object.hasOwn(source, field))
+      .map((field) => [field, source[field]])
+  );
+}
+
+function createBookingDocument(query = {}) {
+  const limit = Math.min(Number(query.limit) || BOOKINGS.length, BOOKINGS.length);
+  const selectedBookings = query.fields?.bookings || null;
+  const selectedPets = query.fields?.pets || null;
+  const includesPet = String(query.include || "")
+    .split(",")
+    .map((entry) => entry.trim())
+    .includes("pet");
+  const rows = BOOKINGS.slice(0, limit);
+  const data = rows.map((booking) => {
+    const includePetLinkage = !selectedBookings || selectedBookings.includes("petId");
+    return {
+      type: "bookings",
+      id: booking.id,
+      attributes: selectFields({ summary: booking.summary }, selectedBookings),
+      ...(includePetLinkage
+        ? {
+            relationships: {
+              pet: {
+                data: { type: "pets", id: booking.petId }
+              }
+            }
+          }
+        : {})
+    };
+  });
+  const included = includesPet
+    ? rows.map((booking) => ({
+        type: "pets",
+        id: booking.petId,
+        attributes: selectFields({
+          name: PETS[booking.petId].name,
+          species: PETS[booking.petId].species
+        }, selectedPets)
+      }))
+    : [];
+
+  return {
+    data,
+    ...(included.length > 0 ? { included } : {}),
+    meta: {
+      page: {
+        nextCursor: limit < BOOKINGS.length ? `after-${rows.at(-1)?.id}` : null
+      }
+    }
+  };
+}
+
+function createFixture() {
+  const resource = createBookingsResource();
+  const calls = [];
+  const service = {
+    async queryDocuments(query, { context }) {
+      calls.push({ query, context });
+      return returnJsonApiDocument(createBookingDocument(query));
+    },
+    async getDocumentById() {
+      return returnJsonApiDocument({ data: createBookingDocument().data[0] });
+    }
+  };
+  const definitions = createCrudJsonApiActions({
+    namespace: "bookings",
+    resource,
+    service,
+    surface: "admin",
+    operations: ["list", "view"],
+    scopeInputValidator: Object.freeze({
+      schema: createSchema({
+        workspaceSlug: { type: "string", required: true }
+      }),
+      mode: "patch"
+    }),
+    scopeInputKeys: ["workspaceSlug"],
+    permissionForOperation: () => ({
+      require: "all",
+      permissions: ["bookings.list"]
+    })
+  });
+  const actions = createActionCatalogue();
+  actions.register({
+    contributorId: "test.generated-bookings",
+    domain: "bookings",
+    actions: definitions
+  });
+  const catalog = createServiceToolCatalog(actions, { maxDirectTools: 0 });
+  const context = Object.freeze({
+    actor: Object.freeze({ id: "user-7" }),
+    permissions: Object.freeze(["bookings.list"]),
+    surface: "admin",
+    workspace: Object.freeze({ slug: "north-clinic" })
+  });
+  return { actions, calls, catalog, context, definitions, resource };
+}
+
+async function loadListContract(fixture, context = fixture.context) {
+  const toolSet = fixture.catalog.resolveToolSet(context);
+  const search = await fixture.catalog.executeToolCall({
+    toolName: "assistant_action_search",
+    argumentsText: JSON.stringify({ query: "bookings list" }),
+    context,
+    toolSet
+  });
+  const contract = await fixture.catalog.executeToolCall({
+    toolName: "assistant_action_contract",
+    argumentsText: JSON.stringify({ actionId: "crud.bookings.list", version: 1 }),
+    context,
+    toolSet
+  });
+  return { contract, search, toolSet };
+}
+
+async function executeList(fixture, toolSet, input, context = fixture.context) {
+  return fixture.catalog.executeToolCall({
+    toolName: "assistant_action_execute",
+    argumentsText: JSON.stringify({
+      actionId: "crud.bookings.list",
+      version: 1,
+      input
+    }),
+    context,
+    toolSet
+  });
+}
+
+function resolveLocalSchemaReference(schema, node) {
+  const reference = node?.allOf?.[0]?.$ref;
+  assert.match(reference || "", /^#\/definitions\//u);
+  return schema.definitions[reference.slice("#/definitions/".length)];
+}
+
+test("generated CRUD list contracts conform through native assistant discovery and execution", async (t) => {
+  const fixture = createFixture();
+  const { contract, search, toolSet } = await loadListContract(fixture);
+  const listDefinition = fixture.definitions.find((entry) => entry.id === "crud.bookings.list");
+
+  assert.equal(search.ok, true);
+  assert.deepEqual(search.result.items.map((entry) => entry.actionId), ["crud.bookings.list"]);
+  assert.equal(contract.ok, true);
+  assert.equal(contract.result.inputSchema.properties.include.type, "string");
+  assert.equal(contract.result.inputSchema.properties.fields.type, "object");
+  assert.equal(Object.hasOwn(contract.result.inputSchema.properties, "workspaceSlug"), false);
+  assert.match(contract.result.description, /include must be a comma-separated string/u);
+  assert.match(contract.result.description, /\{"bookings":\["petId"\],"pets":\["name"\]\}/u);
+  assert.match(contract.result.description, /items\[\]\.lookups\.pet\.name/u);
+  const primaryOutputSchema = resolveLocalSchemaReference(
+    contract.result.outputSchema,
+    contract.result.outputSchema.properties.items.items
+  );
+  const lookupOutputSchema = resolveLocalSchemaReference(
+    contract.result.outputSchema,
+    primaryOutputSchema.properties.lookups
+  );
+  const petOutputSchema = resolveLocalSchemaReference(
+    contract.result.outputSchema,
+    lookupOutputSchema.properties.pet
+  );
+  assert.ok(petOutputSchema.properties.name.anyOf.some((entry) => entry.type === "string"));
+
+  await t.test("full list without fields or include", async () => {
+    const response = await executeList(fixture, toolSet, { limit: 5 });
+    assert.equal(response.ok, true);
+    assert.deepEqual(response.result.result.items, [
+      { id: "41", petId: 7, summary: "Wash and trim" },
+      { id: "42", petId: 8, summary: "Nail trim" }
+    ]);
+    assert.equal(response.result.result.nextCursor, null);
+  });
+
+  await t.test("sparse primary fields only", async () => {
+    const response = await executeList(fixture, toolSet, {
+      fields: { bookings: ["petId"] },
+      limit: 5
+    });
+    assert.equal(response.ok, true);
+    assert.deepEqual(response.result.result.items, [
+      { id: "41", petId: 7 },
+      { id: "42", petId: 8 }
+    ]);
+  });
+
+  await t.test("included relationship without sparse fields", async () => {
+    const response = await executeList(fixture, toolSet, { include: "pet", limit: 5 });
+    assert.equal(response.ok, true);
+    assert.equal(response.result.result.items[0].lookups.pet.name, "Fido");
+    assert.equal(response.result.result.items[0].lookups.pet.species, "dog");
+    assert.equal(response.result.result.items[1].lookups.pet.name, "Mabel");
+  });
+
+  await t.test("included relationship plus sparse primary and related fields", async () => {
+    const response = await executeList(fixture, toolSet, {
+      workspaceSlug: "model-controlled-workspace",
+      include: "pet",
+      fields: { bookings: ["petId"], pets: ["name"] },
+      limit: 5
+    });
+    assert.equal(response.ok, true);
+    assert.notEqual(response.error?.code, "assistant_tool_output_invalid");
+    assert.deepEqual(JSON.parse(JSON.stringify(response.result.result.items)), [
+      {
+        id: "41",
+        petId: 7,
+        lookups: {
+          petId: { id: "7", name: "Fido" },
+          pet: { id: "7", name: "Fido" }
+        }
+      },
+      {
+        id: "42",
+        petId: 8,
+        lookups: {
+          petId: { id: "8", name: "Mabel" },
+          pet: { id: "8", name: "Mabel" }
+        }
+      }
+    ]);
+    assert.equal(Object.hasOwn(response.result.result.items[0], "summary"), false);
+    assert.equal(Object.hasOwn(response.result.result.items[0].lookups.pet, "species"), false);
+    assert.deepEqual(
+      validateSchemaPayload(listDefinition.extensions.assistant.output, response.result.result, {
+        phase: "output"
+      }),
+      response.result.result
+    );
+    assert.equal(fixture.calls.at(-1).query.workspaceSlug, undefined);
+    assert.equal(fixture.calls.at(-1).context.workspace.slug, "north-clinic");
+  });
+
+  await t.test("limit and cursor truncation remain bounded", async () => {
+    const response = await executeList(fixture, toolSet, { limit: 1 });
+    assert.equal(response.ok, true);
+    assert.equal(response.result.result.items.length, 1);
+    assert.equal(response.result.result.nextCursor, "after-41");
+    assert.equal(fixture.calls.at(-1).query.limit, 1);
+  });
+
+  await t.test("invalid array-shaped include gives an actionable validation result", async () => {
+    const response = await executeList(fixture, toolSet, { include: ["pet"] });
+    assert.equal(response.ok, false);
+    assert.equal(response.error.code, "ACTION_VALIDATION_FAILED");
+    assert.equal(response.error.status, 400);
+    assert.match(response.error.message, /include expects a comma-separated string such as "pet,service"/u);
+  });
+
+  await t.test("invalid array-shaped fields gives an actionable validation result", async () => {
+    const response = await executeList(fixture, toolSet, { fields: ["pet.name"] });
+    assert.equal(response.ok, false);
+    assert.equal(response.error.code, "ACTION_VALIDATION_FAILED");
+    assert.equal(response.error.status, 400);
+    assert.match(
+      response.error.message,
+      /fields expects an object such as \{"bookings":\["petId"\],"pets":\["name"\]\}/u
+    );
+  });
+
+  await t.test("permission denial removes the generated action from native discovery", async () => {
+    const deniedContext = {
+      ...fixture.context,
+      permissions: []
+    };
+    const deniedToolSet = fixture.catalog.resolveToolSet(deniedContext);
+    assert.deepEqual(deniedToolSet.tools, []);
+    assert.deepEqual(await fixture.catalog.executeToolCall({
+      toolName: "crud_bookings_list",
+      argumentsText: "{}",
+      context: deniedContext,
+      toolSet: deniedToolSet
+    }), {
+      ok: false,
+      error: {
+        code: "assistant_tool_unknown",
+        message: "Unknown tool."
+      }
+    });
+  });
+});

package/test/defineCrudJsonApiFeature.test.js

@@ -4,6 +4,8 @@ import { createSchema } from "json-rest-schema";
 
 import { createActionProvider } from "@jskit-ai/kernel/server/actions";
 import { createCapabilityRuntime, defineProvider } from "@jskit-ai/kernel/shared/capabilities";
+import { validateSchemaPayload } from "@jskit-ai/kernel/shared/validators";
+import { returnJsonApiDocument } from "@jskit-ai/http-runtime/shared";
 import { defineCrudResource } from "@jskit-ai/resource-crud-core/shared/crudResource";
 import { defineCrudJsonApiFeature } from "../src/server/defineCrudJsonApiFeature.js";
 import { createCrudJsonApiActions } from "../src/server/jsonApiModule/actions.js";
@@ -187,6 +189,91 @@ test("defineCrudJsonApiFeature makes workspace scope and permissions explicit",
   await runtime.shutdown();
 });
 
+test("generated CRUD actions expose truthful assistant contracts without changing native results", async () => {
+  const resource = createBookResource();
+  const document = (id, title) => ({
+    data: {
+      type: "books",
+      id,
+      attributes: { title }
+    }
+  });
+  const actions = createCrudJsonApiActions({
+    namespace: "books",
+    resource,
+    service: {
+      async queryDocuments() {
+        return returnJsonApiDocument({
+          data: [document("1", "Kindred").data],
+          meta: { page: { nextCursor: "cursor-2" } }
+        });
+      },
+      async getDocumentById() {
+        return returnJsonApiDocument(document("1", "Kindred"));
+      },
+      async createDocument() {
+        return returnJsonApiDocument(document("2", "Parable of the Sower"));
+      },
+      async patchDocumentById() {
+        return returnJsonApiDocument(document("1", "Kindred (updated)"));
+      },
+      async deleteDocumentById() {
+        return null;
+      }
+    },
+    surface: "admin",
+    permissionForOperation: () => ({ require: "authenticated" })
+  });
+  const byOperation = new Map(actions.map((entry) => [entry.id.split(".").at(-1), entry]));
+
+  assert.ok(actions.every((entry) => entry.output === null));
+  assert.notEqual(byOperation.get("list").extensions.assistant.output, resource.operations.list.output);
+  assert.notEqual(byOperation.get("view").extensions.assistant.output, resource.operations.view.output);
+  assert.equal(byOperation.get("create").extensions.assistant.output, resource.operations.create.output);
+  assert.equal(byOperation.get("update").extensions.assistant.output, resource.operations.patch.output);
+  assert.equal(byOperation.get("delete").extensions.assistant.output, resource.operations.delete.output);
+  const sparseListContract = byOperation.get("list").extensions.assistant.output.schema.toJsonSchema({ mode: "replace" });
+  const sparseListItemContract = Object.values(sparseListContract.definitions)[0];
+  assert.deepEqual(sparseListItemContract.required, ["id"]);
+  assert.deepEqual(
+    byOperation.get("view").extensions.assistant.output.schema.toJsonSchema({ mode: "replace" }).required,
+    ["id"]
+  );
+
+  const transform = async (operation, input = {}) => {
+    const definition = byOperation.get(operation);
+    const nativeResult = await definition.execute(input, {});
+    const assistantResult = await definition.extensions.assistant.transformResult(nativeResult, { input });
+    return validateSchemaPayload(definition.extensions.assistant.output, assistantResult, {
+      phase: "output"
+    });
+  };
+
+  assert.deepEqual(await transform("list"), {
+    items: [{ id: "1", title: "Kindred" }],
+    nextCursor: "cursor-2"
+  });
+  assert.deepEqual(await transform("view", { recordId: "1" }), {
+    id: "1",
+    title: "Kindred"
+  });
+  assert.deepEqual(await transform("create", { title: "Parable of the Sower" }), {
+    id: "2",
+    title: "Parable of the Sower"
+  });
+  assert.deepEqual(await transform("update", { recordId: "1", title: "Kindred (updated)" }), {
+    id: "1",
+    title: "Kindred (updated)"
+  });
+  assert.deepEqual(await transform("delete", { recordId: "1" }), {
+    id: "1",
+    deleted: true
+  });
+
+  assert.deepEqual(await byOperation.get("view").execute({ recordId: "1" }, {}),
+    returnJsonApiDocument(document("1", "Kindred")));
+});
+
 test("defineCrudJsonApiFeature lets product services name exact capability dependencies", async () => {
   const routes = [];
   const access = {