@carlonicora/nestjs-neo4jsonapi 4.2.0 → 4.3.0

package/dist/agents/operator/tools/entity-write.tools.js

@@ -16,9 +16,18 @@ const common_1 = require("@nestjs/common");
 const node_crypto_1 = require("node:crypto");
 const zod_1 = require("zod");
 const entity_service_registry_1 = require("../../../common/registries/entity.service.registry");
+const blocknote_service_1 = require("../../../core/blocknote/services/blocknote.service");
 const graph_catalog_service_1 = require("../../graph/services/graph.catalog.service");
+const richtext_write_1 = require("../../graph/services/richtext.write");
 const scope_guard_1 = require("../../graph/services/scope.guard");
+const writable_rules_1 = require("../../graph/services/writable.rules");
 const tool_factory_1 = require("../../graph/tools/tool.factory");
+/**
+ * Label used whenever a referenced record cannot be resolved to a name — it does
+ * not exist, or it sits outside the run's scope. NEVER fall back to the id: the
+ * approval card must not leak ids, nor names from another scope.
+ */
+const NOT_FOUND_LABEL = "(not found)";
 const isError = (value) => typeof value === "object" && value !== null && "error" in value;
 /**
  * Generic, catalog-driven create/update/delete/link/unlink tools for the operator.
@@ -28,14 +37,23 @@ const isError = (value) => typeof value === "object" && value !== null && "error
  * 1. **Opt-in.** Only descriptors that declare `chat.writable` are touchable, and
  *    only when the caller's modules grant access. When nothing is writable the
  *    tools are not built at all, so a host application that never opts in sees
- *    exactly the tool set it had before.
+ *    exactly the tool set it had before. `chat.writable` may narrow further to an
+ *    allow-list of fields and relationships, which `describe_entity` reports and
+ *    every check here enforces.
  * 2. **Scoped.** Every id in every payload is checked through `ScopeGuard`, and
  *    `create` overwrites the scope relationship with the run's OWN scope id — the
  *    model cannot name a different one. The scope relationship itself can never be
  *    re-pointed, so a record cannot be moved between scope roots.
- * 3. **Service-only.** Writes go through `EntityServiceRegistry.get(type)`, i.e. the
- *    AbstractService, never the repository — so the host application's side effects
- *    (audit log, knowledge-graph chunking, cache invalidation) all fire. No Cypher
+ * 3. **Service-only, through the same DTO path the controllers use.** Writes go
+ *    through `EntityServiceRegistry.get(type)`, i.e. the AbstractService, never the
+ *    repository — and always via its `*FromDTO` helpers with a `JsonApiDTOData`,
+ *    exactly as an HTTP controller does. That is what makes a host application's
+ *    OVERRIDE of `createFromDTO` / `patchFromDTO` fire (ownership checks,
+ *    knowledge-graph and summariser scheduling, cache invalidation) and what lets
+ *    `mapDTOToParams` fill `contextKey` relationships from CLS. Calling the plain
+ *    `create` / `patch` would skip every one of those: the record is written, the
+ *    app's read query for its type then finds nothing (a required owner edge is
+ *    missing) and the tool reports `not found` for a record that exists. No Cypher
  *    is written here.
  */
 let EntityWriteTools = EntityWriteTools_1 = class EntityWriteTools {
@@ -46,11 +64,19 @@ let EntityWriteTools = EntityWriteTools_1 = class EntityWriteTools {
      * from GraphModule — a missing provider fails loudly at boot rather than
      * silently dropping the per-turn tool-call audit trail.
      */
-    factory) {
+    factory, 
+    /**
+     * Optional in the TYPE signature for the same reason as `factory`, and
+     * resolved from GraphModule (which re-exports BlockNoteModule) exactly the
+     * same way. Without it a rich-text field would pass through as the model's
+     * raw markdown; see `convertRichtextFields`.
+     */
+    blockNote) {
         this.catalog = catalog;
         this.registry = registry;
         this.scopeGuard = scopeGuard;
         this.factory = factory;
+        this.blockNote = blockNote;
         this.logger = new common_1.Logger(EntityWriteTools_1.name);
     }
     /**
@@ -70,16 +96,21 @@ let EntityWriteTools = EntityWriteTools_1 = class EntityWriteTools {
             type: typeField,
             fields: zod_1.z
                 .record(zod_1.z.string(), zod_1.z.any())
-                .describe("Field values keyed by field name. Call describe_entity first to learn the valid field names."),
+                .describe("Field values keyed by field name. Call describe_entity first to learn the valid field names. " +
+                "Only fields describe_entity marks writable may be set."),
             relationships: zod_1.z
                 .record(zod_1.z.string(), zod_1.z.string())
                 .optional()
-                .describe("Related record ids keyed by relationship name, for relationships declared on this type."),
+                .describe("Related record ids keyed by relationship name, for relationships declared on this type. " +
+                "Only relationships describe_entity marks writable may be set."),
         });
         const updateSchema = zod_1.z.object({
             type: typeField,
             id: zod_1.z.string().describe("Id of the record to update."),
-            fields: zod_1.z.record(zod_1.z.string(), zod_1.z.any()).describe("Only the field values that change. Others are left untouched."),
+            fields: zod_1.z
+                .record(zod_1.z.string(), zod_1.z.any())
+                .describe("Only the field values that change. Others are left untouched. " +
+                "Only fields describe_entity marks writable may be set."),
         });
         const deleteSchema = zod_1.z.object({
             type: typeField,
@@ -88,29 +119,42 @@ let EntityWriteTools = EntityWriteTools_1 = class EntityWriteTools {
         const linkSchema = zod_1.z.object({
             type: typeField,
             id: zod_1.z.string().describe("Id of the record whose relationship changes."),
-            relationship: zod_1.z.string().describe("Relationship name as reported by describe_entity."),
+            relationship: zod_1.z
+                .string()
+                .describe("Relationship name as reported by describe_entity. " +
+                "Only relationships describe_entity marks writable may be set."),
             targetIds: zod_1.z.array(zod_1.z.string()).describe("Ids of the related records."),
         });
         return [
             {
                 tool: new tools_1.DynamicStructuredTool({
                     name: "create_entity",
-                    description: `Creates one new record. Writable types: ${types}. This action requires user approval before it runs.`,
+                    description: `Creates one new record. Writable types: ${types}. ` +
+                        "Only fields describe_entity marks writable may be set, and only relationships describe_entity marks writable. " +
+                        richtext_write_1.RICHTEXT_HINT +
+                        " This action requires user approval before it runs.",
                     schema: createSchema,
                     func: async (input) => JSON.stringify(await this.createEntity(input, ctx, recorder)),
                 }),
                 destructive: true,
                 summarise: (args) => this.summariseCreate(args),
+                present: (args) => this.presentCreate(args, ctx),
+                validate: async (args) => this.rejection(await this.prepareCreate(args, ctx)),
             },
             {
                 tool: new tools_1.DynamicStructuredTool({
                     name: "update_entity",
-                    description: `Updates the given fields of one existing record, leaving every other field untouched. Writable types: ${types}. This action requires user approval before it runs.`,
+                    description: `Updates the given fields of one existing record, leaving every other field untouched. Writable types: ${types}. ` +
+                        "Only fields describe_entity marks writable may be set. " +
+                        richtext_write_1.RICHTEXT_HINT +
+                        " This action requires user approval before it runs.",
                     schema: updateSchema,
                     func: async (input) => JSON.stringify(await this.updateEntity(input, ctx, recorder)),
                 }),
                 destructive: true,
-                summarise: (args) => this.summariseUpdate(args),
+                summarise: (args) => this.summariseUpdate(args, ctx),
+                present: (args) => this.presentUpdate(args, ctx),
+                validate: async (args) => this.rejection(await this.prepareUpdate(args, ctx)),
             },
             {
                 tool: new tools_1.DynamicStructuredTool({
@@ -120,101 +164,91 @@ let EntityWriteTools = EntityWriteTools_1 = class EntityWriteTools {
                     func: async (input) => JSON.stringify(await this.deleteEntity(input, ctx, recorder)),
                 }),
                 destructive: true,
-                summarise: (args) => this.summariseDelete(args),
+                summarise: (args) => this.summariseDelete(args, ctx),
+                present: (args) => this.presentDelete(args, ctx),
+                validate: async (args) => this.rejection(await this.prepareDelete(args, ctx)),
             },
             {
                 tool: new tools_1.DynamicStructuredTool({
                     name: "link_entities",
-                    description: `Adds related records to one relationship of an existing record. Writable types: ${types}. This action requires user approval before it runs.`,
+                    description: `Adds related records to one relationship of an existing record. Writable types: ${types}. ` +
+                        "Only relationships describe_entity marks writable may be set. " +
+                        "This action requires user approval before it runs.",
                     schema: linkSchema,
                     func: async (input) => JSON.stringify(await this.linkEntities(input, ctx, recorder)),
                 }),
                 destructive: true,
-                summarise: (args) => this.summariseLink(args, "Link"),
+                summarise: (args) => this.summariseLink(args, "Link", ctx),
+                present: (args) => this.presentLink(args, ctx),
+                validate: async (args) => this.rejection(await this.prepareLink(args, ctx, "link")),
             },
             {
                 tool: new tools_1.DynamicStructuredTool({
                     name: "unlink_entities",
-                    description: `Removes related records from one relationship of an existing record. Writable types: ${types}. This action requires user approval before it runs.`,
+                    description: `Removes related records from one relationship of an existing record. Writable types: ${types}. ` +
+                        "Only relationships describe_entity marks writable may be set. " +
+                        "This action requires user approval before it runs.",
                     schema: linkSchema,
                     func: async (input) => JSON.stringify(await this.unlinkEntities(input, ctx, recorder)),
                 }),
                 destructive: true,
-                summarise: (args) => this.summariseLink(args, "Unlink"),
+                summarise: (args) => this.summariseLink(args, "Unlink", ctx),
+                present: (args) => this.presentLink(args, ctx),
+                validate: async (args) => this.rejection(await this.prepareLink(args, ctx, "unlink")),
             },
         ];
     }
     async createEntity(input, ctx, recorder) {
         return this.capture("create_entity", input, recorder, async () => {
-            const entity = this.resolveWritable(input.type, ctx);
-            if (isError(entity))
-                return entity;
-            const fields = input.fields ?? {};
-            const fieldError = this.validateFields(entity, fields);
-            if (fieldError)
-                return { error: fieldError };
-            // The run's scope is authoritative: whatever the model supplied for the
-            // scope relationship is discarded before validation and replaced below.
-            const scopeKey = this.scopeKeyOf(entity);
-            const relationships = { ...(input.relationships ?? {}) };
-            if (scopeKey)
-                delete relationships[scopeKey];
-            const relationshipError = await this.validateRelationships(entity, relationships, ctx);
-            if (relationshipError)
-                return { error: relationshipError };
-            const service = this.registry.get(entity.type);
-            if (!service)
-                return { error: `Service not available for "${entity.type}".` };
+            const prepared = await this.prepareCreate(input, ctx);
+            if (isError(prepared))
+                return prepared;
+            const { entity, service, fields, relationships } = prepared;
             const id = (0, node_crypto_1.randomUUID)();
             return this.dispatch(async () => {
-                await service.create({
+                // The model writes markdown into a rich-text field, because that is what
+                // the read side rendered for it. Storing it verbatim leaves a record the
+                // frontend cannot render at all, so it becomes a BlockNote document here
+                // — after validation (which checks the markdown is a string) and after
+                // the approval card, which shows the model's own text.
+                const attributes = await (0, richtext_write_1.convertRichtextFields)(this.blockNote, entity, fields);
+                const data = {
+                    type: entity.type,
                     id,
-                    ...fields,
-                    ...relationships,
-                    ...(scopeKey && ctx.scopeId ? { [scopeKey]: ctx.scopeId } : {}),
-                });
+                    attributes,
+                    relationships: this.createRelationships({ entity, relationships, ctx }),
+                };
+                await service.createFromDTO({ data });
                 return { id, type: entity.type, created: true };
             });
         });
     }
     async updateEntity(input, ctx, recorder) {
         return this.capture("update_entity", input, recorder, async () => {
-            const entity = this.resolveWritable(input.type, ctx);
-            if (isError(entity))
-                return entity;
-            const outOfScope = await this.requireInScope(entity.type, [input.id], ctx);
-            if (outOfScope)
-                return outOfScope;
-            const fields = input.fields ?? {};
-            const fieldError = this.validateFields(entity, fields);
-            if (fieldError)
-                return { error: fieldError };
-            const service = this.registry.get(entity.type);
-            if (!service)
-                return { error: `Service not available for "${entity.type}".` };
+            const prepared = await this.prepareUpdate(input, ctx);
+            if (isError(prepared))
+                return prepared;
+            const { entity, service, fields, id } = prepared;
             return this.dispatch(async () => {
+                // Markdown in a rich-text field becomes a BlockNote document; see createEntity.
+                const attributes = await (0, richtext_write_1.convertRichtextFields)(this.blockNote, entity, fields);
                 // patch, not put: only the named fields change. put would map every
                 // descriptor relationship and treat the ones absent from the payload as
                 // "delete all edges", silently stripping the record's relationships.
-                await service.patch({ id: input.id, ...fields });
-                return { id: input.id, type: entity.type, updated: true };
+                await service.patchFromDTO({ data: { type: entity.type, id, attributes } });
+                return { id, type: entity.type, updated: true };
             });
         });
     }
     async deleteEntity(input, ctx, recorder) {
         return this.capture("delete_entity", input, recorder, async () => {
-            const entity = this.resolveWritable(input.type, ctx);
-            if (isError(entity))
-                return entity;
-            const outOfScope = await this.requireInScope(entity.type, [input.id], ctx);
-            if (outOfScope)
-                return outOfScope;
-            const service = this.registry.get(entity.type);
-            if (!service)
-                return { error: `Service not available for "${entity.type}".` };
+            const prepared = await this.prepareDelete(input, ctx);
+            if (isError(prepared))
+                return prepared;
+            const { entity, service, id } = prepared;
             return this.dispatch(async () => {
-                await service.delete({ id: input.id });
-                return { id: input.id, type: entity.type, deleted: true };
+                await service.delete({ id });
+                return { id, type: entity.type, deleted: true };
             });
         });
     }
@@ -225,6 +259,115 @@ let EntityWriteTools = EntityWriteTools_1 = class EntityWriteTools {
         return this.capture("unlink_entities", input, recorder, () => this.applyLink(input, ctx, "unlink"));
     }
     // ---------------------------------------------------------------------------
+    // Preparation
+    //
+    // Every check a write performs lives here, once per tool, so the `validate`
+    // hook — which runs BEFORE the user is asked to approve anything — rejects
+    // exactly the calls the execution path rejects, with exactly the same message.
+    // A prepared result carries the payload the write then uses, so a check never
+    // has to be repeated at write time.
+    //
+    // Tool args reach `validate` straight from the model, unvalidated by the zod
+    // schema, so every accessor here is defensive about shape.
+    // ---------------------------------------------------------------------------
+    async prepareCreate(input, ctx) {
+        const entity = this.resolveWritable(input?.type, ctx);
+        if (isError(entity))
+            return entity;
+        const fields = this.toValueMap(input?.fields);
+        const fieldError = this.validateFields(entity, fields);
+        if (fieldError)
+            return { error: fieldError };
+        // The run's scope is authoritative: whatever the model supplied for the scope
+        // relationship is discarded here and replaced at write time.
+        const scopeKey = (0, writable_rules_1.scopeKeyOf)(entity);
+        const relationships = this.toValueMap(input?.relationships);
+        if (scopeKey)
+            delete relationships[scopeKey];
+        const relationshipError = await this.validateRelationships(entity, relationships, ctx);
+        if (relationshipError)
+            return { error: relationshipError };
+        const service = this.registry.get(entity.type);
+        if (!service)
+            return { error: `Service not available for "${entity.type}".` };
+        return { entity, service, fields, relationships };
+    }
+    async prepareUpdate(input, ctx) {
+        const entity = this.resolveWritable(input?.type, ctx);
+        if (isError(entity))
+            return entity;
+        const id = this.toId(input?.id);
+        const outOfScope = await this.requireInScope(entity.type, [id], ctx);
+        if (outOfScope)
+            return outOfScope;
+        const fields = this.toValueMap(input?.fields);
+        const fieldError = this.validateFields(entity, fields);
+        if (fieldError)
+            return { error: fieldError };
+        const service = this.registry.get(entity.type);
+        if (!service)
+            return { error: `Service not available for "${entity.type}".` };
+        return { entity, service, id, fields };
+    }
+    async prepareDelete(input, ctx) {
+        const entity = this.resolveWritable(input?.type, ctx);
+        if (isError(entity))
+            return entity;
+        const id = this.toId(input?.id);
+        const outOfScope = await this.requireInScope(entity.type, [id], ctx);
+        if (outOfScope)
+            return outOfScope;
+        const service = this.registry.get(entity.type);
+        if (!service)
+            return { error: `Service not available for "${entity.type}".` };
+        return { entity, service, id };
+    }
+    async prepareLink(input, ctx, mode) {
+        const entity = this.resolveWritable(input?.type, ctx);
+        if (isError(entity))
+            return entity;
+        const relationship = entity.relationships.find((candidate) => candidate.name === input?.relationship);
+        if (!relationship) {
+            return {
+                error: `Relationship "${input?.relationship}" is not available on ${entity.type}. Valid relationships: [${entity.relationships
+                    .map((candidate) => candidate.name)
+                    .join(", ")}].`,
+            };
+        }
+        const rejection = this.rejectUnwritableRelationship(entity, relationship);
+        if (rejection)
+            return { error: rejection };
+        const targetIds = Array.isArray(input?.targetIds) ? input.targetIds.map((id) => String(id)) : [];
+        if (!targetIds.length)
+            return { error: "targetIds must contain at least one id." };
+        if (relationship.cardinality === "one") {
+            if (mode === "unlink") {
+                // A to-one edge cannot be removed through the generic patch path: the
+                // repository maps an empty list to "no change", so the edge would survive
+                // while the tool reported success.
+                return {
+                    error: `Relationship "${relationship.name}" on ${entity.type} holds a single record and cannot be cleared. Link a different record instead.`,
+                };
+            }
+            if (targetIds.length !== 1) {
+                return { error: `Relationship "${relationship.name}" on ${entity.type} accepts exactly one record.` };
+            }
+        }
+        const id = this.toId(input?.id);
+        const outOfScope = (await this.requireInScope(entity.type, [id], ctx)) ??
+            (await this.requireInScope(relationship.targetType, targetIds, ctx));
+        if (outOfScope)
+            return outOfScope;
+        const service = this.registry.get(entity.type);
+        if (!service)
+            return { error: `Service not available for "${entity.type}".` };
+        return { entity, service, id, relationship, targetIds };
+    }
+    /** The `validate` hook's answer: the rejection message, or `null` when the call may proceed. */
+    rejection(prepared) {
+        return isError(prepared) ? prepared.error : null;
+    }
+    // ---------------------------------------------------------------------------
     // Guards
     // ---------------------------------------------------------------------------
     resolveWritable(type, ctx) {
@@ -236,7 +379,13 @@ let EntityWriteTools = EntityWriteTools_1 = class EntityWriteTools {
         }
         return entity;
     }
-    /** Reject any field the catalog does not declare, and any type mismatch. */
+    /**
+     * Reject any field the catalog does not declare, any field the descriptor does
+     * not open to the assistant, and any type mismatch. The writable list is what
+     * keeps the model out of the fields the system generates itself (a tldr, a
+     * summary, an ai status): they are described — the model can read them — but
+     * writing them would overwrite generated content with a guess.
+     */
     validateFields(entity, fields) {
         const byName = new Map(entity.fields.map((field) => [field.name, field]));
         for (const [name, value] of Object.entries(fields)) {
@@ -246,6 +395,9 @@ let EntityWriteTools = EntityWriteTools_1 = class EntityWriteTools {
                     .map((field) => field.name)
                     .join(", ")}].`;
             }
+            if (!(0, writable_rules_1.isFieldWritable)(entity, name)) {
+                return `Field "${name}" on ${entity.type} is not writable. Writable fields: [${(0, writable_rules_1.writableFieldNames)(entity).join(", ")}].`;
+            }
             if (!this.matchesType(definition.type, value)) {
                 return `Field "${name}" on ${entity.type} expects ${definition.type}.`;
             }
@@ -277,25 +429,23 @@ let EntityWriteTools = EntityWriteTools_1 = class EntityWriteTools {
         return null;
     }
     /**
-     * A relationship the generic write path must never touch:
-     * - reverse relationships are serialisation-only, with no edge on this side;
-     * - polymorphic relationships are a read-only chat traversal: they carry no
-     *   single target type, so there is nothing for the write path to resolve
-     *   (`targetType` is the "*" placeholder, which no scope check can honour);
-     * - the scope relationship is what confines the record to the run's root, so
-     *   re-pointing it would move the record into another scope.
+     * The message for a relationship the generic write path must never touch. The
+     * reasons themselves live in `writable.rules` — the same predicate
+     * `describe_entity` uses to tell the model what it may write, so what the model
+     * is told and what is enforced here cannot drift.
      */
     rejectUnwritableRelationship(entity, relationship) {
-        if (relationship.isReverse) {
-            return `Relationship "${relationship.name}" on ${entity.type} is read-only and cannot be written.`;
-        }
-        if (relationship.polymorphic) {
-            return `Relationship "${relationship.name}" on ${entity.type} is read-only and cannot be written.`;
-        }
-        if (relationship.name === this.scopeKeyOf(entity)) {
-            return `Relationship "${relationship.name}" on ${entity.type} cannot be changed.`;
+        switch ((0, writable_rules_1.relationshipRejection)(entity, relationship)) {
+            case "reverse":
+            case "polymorphic":
+                return `Relationship "${relationship.name}" on ${entity.type} is read-only and cannot be written.`;
+            case "scope":
+                return `Relationship "${relationship.name}" on ${entity.type} cannot be changed.`;
+            case "notListed":
+                return `Relationship "${relationship.name}" on ${entity.type} is not writable. Writable relationships: [${(0, writable_rules_1.writableRelationshipNames)(entity).join(", ")}].`;
+            default:
+                return null;
         }
-        return null;
     }
     /** `null` when every id is inside the run's scope, otherwise the error to return. */
     async requireInScope(type, ids, ctx) {
@@ -312,12 +462,48 @@ let EntityWriteTools = EntityWriteTools_1 = class EntityWriteTools {
     // Internals
     // ---------------------------------------------------------------------------
     /**
-     * The scope chain is guaranteed to be exactly one hop for writable types — the
-     * catalog rejects deeper writables at boot — so the first hop's key is the
-     * relationship that pins a new record to the run's scope root.
+     * The JSON:API `relationships` object a create sends, built from three sources:
+     *
+     * 1. what the model supplied, keyed by the descriptor's `dtoKey` (NOT the catalog
+     *    name — `mapDTOToParams` looks relationships up by `dtoKey`, so a payload
+     *    keyed by name is dropped without a word whenever the two differ);
+     * 2. the run's OWN scope root, which overwrites anything the model named — the
+     *    model's value was already stripped while preparing;
+     * 3. the owner, from the run's user. The host application's clients send this on
+     *    every create, and its read query for the type requires the edge: without it
+     *    the record is written and then cannot be read back.
      */
-    scopeKeyOf(entity) {
-        return entity.scope?.path[0]?.key;
+    createRelationships(params) {
+        const { entity, relationships, ctx } = params;
+        const byName = new Map(entity.relationships.map((relationship) => [relationship.name, relationship]));
+        const data = {};
+        for (const [name, value] of Object.entries(relationships)) {
+            const relationship = byName.get(name);
+            if (!relationship)
+                continue;
+            const ids = this.toIdList(value);
+            if (!ids.length)
+                continue;
+            data[relationship.dtoKey] =
+                relationship.cardinality === "one"
+                    ? { data: { type: relationship.targetType, id: ids[0] } }
+                    : { data: ids.map((targetId) => ({ type: relationship.targetType, id: targetId })) };
+        }
+        const hop = entity.scope?.path[0];
+        if (hop && ctx.scopeId)
+            data[hop.dtoKey] = { data: { type: hop.targetType, id: ctx.scopeId } };
+        if (entity.owner && ctx.userId) {
+            data[entity.owner.dtoKey] = { data: { type: entity.owner.type, id: ctx.userId } };
+        }
+        return data;
+    }
+    /** A payload map from raw tool args: anything that is not a plain object is empty. */
+    toValueMap(value) {
+        return value && typeof value === "object" && !Array.isArray(value) ? { ...value } : {};
+    }
+    /** An id from raw tool args; a missing one becomes `""`, which no scope check passes. */
+    toId(value) {
+        return typeof value === "string" ? value : value === null || value === undefined ? "" : String(value);
     }
     writableTypes(ctx) {
         return this.catalog
@@ -348,64 +534,39 @@ let EntityWriteTools = EntityWriteTools_1 = class EntityWriteTools {
         }
     }
     async applyLink(input, ctx, mode) {
-        const entity = this.resolveWritable(input.type, ctx);
-        if (isError(entity))
-            return entity;
-        const relationship = entity.relationships.find((candidate) => candidate.name === input.relationship);
-        if (!relationship) {
-            return {
-                error: `Relationship "${input.relationship}" is not available on ${entity.type}. Valid relationships: [${entity.relationships
-                    .map((candidate) => candidate.name)
-                    .join(", ")}].`,
-            };
-        }
-        const rejection = this.rejectUnwritableRelationship(entity, relationship);
-        if (rejection)
-            return { error: rejection };
-        const targetIds = (input.targetIds ?? []).map((id) => String(id));
-        if (!targetIds.length)
-            return { error: "targetIds must contain at least one id." };
-        if (relationship.cardinality === "one") {
-            if (mode === "unlink") {
-                // A to-one edge cannot be removed through the generic patch path: the
-                // repository maps an empty list to "no change", so the edge would survive
-                // while the tool reported success.
-                return {
-                    error: `Relationship "${relationship.name}" on ${entity.type} holds a single record and cannot be cleared. Link a different record instead.`,
-                };
-            }
-            if (targetIds.length !== 1) {
-                return { error: `Relationship "${relationship.name}" on ${entity.type} accepts exactly one record.` };
-            }
-        }
-        const outOfScope = (await this.requireInScope(entity.type, [input.id], ctx)) ??
-            (await this.requireInScope(relationship.targetType, targetIds, ctx));
-        if (outOfScope)
-            return outOfScope;
-        const service = this.registry.get(entity.type);
-        if (!service)
-            return { error: `Service not available for "${entity.type}".` };
+        const prepared = await this.prepareLink(input, ctx, mode);
+        if (isError(prepared))
+            return prepared;
+        const { entity, service, id, relationship, targetIds } = prepared;
         return this.dispatch(async () => {
             if (relationship.cardinality === "one") {
                 // The framework's add/remove relationship helpers are to-many only, so a
                 // to-one edge is repointed with patch, which replaces the single edge.
-                await service.patch({ id: input.id, [relationship.name]: targetIds });
+                await service.patchFromDTO({
+                    data: {
+                        type: entity.type,
+                        id,
+                        relationships: {
+                            [relationship.dtoKey]: { data: { type: relationship.targetType, id: targetIds[0] } },
+                        },
+                    },
+                });
             }
             else if (mode === "link") {
                 await service.addToRelationshipFromDTO({
-                    id: input.id,
+                    id,
                     relationship: relationship.name,
-                    data: targetIds.map((id) => ({ id, type: relationship.targetType })),
+                    data: targetIds.map((targetId) => ({ id: targetId, type: relationship.targetType })),
                 });
             }
             else {
                 await service.removeFromRelationshipFromDTO({
-                    id: input.id,
+                    id,
                     relationship: relationship.name,
-                    data: targetIds.map((id) => ({ id, type: relationship.targetType })),
+                    data: targetIds.map((targetId) => ({ id: targetId, type: relationship.targetType })),
                 });
             }
-            return { id: input.id, type: entity.type, relationship: relationship.name, targetIds, [mode + "ed"]: true };
+            return { id, type: entity.type, relationship: relationship.name, targetIds, [mode + "ed"]: true };
         });
     }
     /**
@@ -428,43 +589,154 @@ let EntityWriteTools = EntityWriteTools_1 = class EntityWriteTools {
         return this.factory ? this.factory.capture({ tool, input }, fn, recorder) : fn();
     }
     // ---------------------------------------------------------------------------
+    // Name resolution
+    //
+    // The approval card shows NAMES, never ids. Every referenced record is resolved
+    // here, through the scope guard first: an id the run may not see resolves to
+    // "(not found)" so a cross-scope name can never leak.
+    // ---------------------------------------------------------------------------
+    async resolveRef(params) {
+        const { type, id, ctx } = params;
+        const unresolved = { id, type, label: NOT_FOUND_LABEL };
+        try {
+            if (!(await this.scopeGuard.isInScope({ type, id, ctx })))
+                return unresolved;
+            const record = await this.registry.get(type)?.findRecordById({ id });
+            if (!record)
+                return unresolved;
+            const catalogEntity = this.catalog.getEntityDetail(type, ctx.userModuleIds);
+            const candidate = catalogEntity?.summary?.(record) ??
+                record.name ??
+                record.title ??
+                NOT_FOUND_LABEL;
+            const label = typeof candidate === "string" && candidate ? candidate : NOT_FOUND_LABEL;
+            return { id, type, label };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            this.logger.warn(`entity-write: could not resolve the name of a ${type} record: ${message}`);
+            return unresolved;
+        }
+    }
+    /** Resolve the record the tool call targets, from `args.type` / `args.id`. */
+    async resolveTargetRef(args, ctx) {
+        const type = this.argType(args);
+        const id = typeof args.id === "string" ? args.id : "";
+        if (!id)
+            return { id: "", type, label: NOT_FOUND_LABEL };
+        return this.resolveRef({ type, id, ctx });
+    }
+    /** Relationship payloads are `Record<string, string>` by schema; arrays are accepted defensively. */
+    toIdList(value) {
+        if (value === null || value === undefined)
+            return [];
+        return (Array.isArray(value) ? value : [value]).map((id) => String(id)).filter((id) => id.length > 0);
+    }
+    /** `"Marcus"` when resolved, bare `(not found)` when not — an id is never rendered. */
+    quote(label) {
+        return label === NOT_FOUND_LABEL ? NOT_FOUND_LABEL : `"${label}"`;
+    }
+    // ---------------------------------------------------------------------------
     // Approval-card summaries
     //
-    // These are rendered to the user before the action runs. They stay generic:
-    // nothing beyond the tool's own arguments is named.
+    // These are rendered to the user before the action runs. Referenced records
+    // are named, never identified: no id ever reaches this text.
     // ---------------------------------------------------------------------------
     summariseCreate(args) {
-        const type = this.summariseType(args);
+        const type = this.argType(args);
         const label = this.summariseLabel(args.fields);
         return label ? `Create a new ${type} record named "${label}".` : `Create a new ${type} record.`;
     }
-    summariseUpdate(args) {
-        const type = this.summariseType(args);
+    async summariseUpdate(args, ctx) {
+        const type = this.argType(args);
         const fields = args.fields && typeof args.fields === "object" ? Object.keys(args.fields) : [];
         const changed = fields.length ? ` (${fields.join(", ")})` : "";
-        return `Update the ${type} record ${this.summariseId(args)}${changed}.`;
+        const target = await this.resolveTargetRef(args, ctx);
+        return `Update the ${type} record ${this.quote(target.label)}${changed}.`;
     }
-    summariseDelete(args) {
-        return `Delete the ${this.summariseType(args)} record ${this.summariseId(args)}.`;
+    async summariseDelete(args, ctx) {
+        const target = await this.resolveTargetRef(args, ctx);
+        return `Delete the ${this.argType(args)} record ${this.quote(target.label)}.`;
     }
-    summariseLink(args, verb) {
-        const count = Array.isArray(args.targetIds) ? args.targetIds.length : 0;
-        const relationship = typeof args.relationship === "string" ? args.relationship : "related";
+    async summariseLink(args, verb, ctx) {
+        const relationship = typeof args.relationship === "string" && args.relationship ? args.relationship : "related";
         const preposition = verb === "Link" ? "to" : "from";
-        return `${verb} ${count} record(s) ${preposition} the "${relationship}" relationship of the ${this.summariseType(args)} record ${this.summariseId(args)}.`;
+        const target = await this.resolveTargetRef(args, ctx);
+        const targets = await this.resolveLinkTargets(args, ctx);
+        const named = targets.length ? targets.map((ref) => this.quote(ref.label)).join(", ") : "no records";
+        return `${verb} ${named} ${preposition} the "${relationship}" relationship of the ${this.argType(args)} record ${this.quote(target.label)}.`;
     }
-    summariseType(args) {
+    argType(args) {
         return typeof args.type === "string" && args.type ? args.type : "record";
     }
-    summariseId(args) {
-        return typeof args.id === "string" && args.id ? args.id : "(unknown id)";
-    }
     summariseLabel(fields) {
         if (!fields || typeof fields !== "object")
             return undefined;
         const candidate = fields.name ?? fields.title;
         return typeof candidate === "string" && candidate ? candidate : undefined;
     }
+    // ---------------------------------------------------------------------------
+    // Approval-card proposals
+    //
+    // The structured, name-resolved rendering the card reads instead of toolArgs.
+    // ---------------------------------------------------------------------------
+    async presentCreate(args, ctx) {
+        const type = this.argType(args);
+        const entity = this.catalog.getEntityDetail(type, ctx.userModuleIds);
+        const scopeKey = entity ? (0, writable_rules_1.scopeKeyOf)(entity) : undefined;
+        const byName = new Map((entity?.relationships ?? []).map((relationship) => [relationship.name, relationship]));
+        const raw = args.relationships && typeof args.relationships === "object" ? args.relationships : {};
+        const relationships = {};
+        for (const [name, value] of Object.entries(raw)) {
+            // The run's own scope is not a user choice — it is never shown.
+            if (scopeKey && name === scopeKey)
+                continue;
+            const targetType = byName.get(name)?.targetType ?? name;
+            const refs = [];
+            for (const id of this.toIdList(value))
+                refs.push(await this.resolveRef({ type: targetType, id, ctx }));
+            if (refs.length)
+                relationships[name] = refs;
+        }
+        return {
+            type,
+            attributes: this.presentAttributes(args),
+            ...(Object.keys(relationships).length ? { relationships } : {}),
+        };
+    }
+    async presentUpdate(args, ctx) {
+        return {
+            type: this.argType(args),
+            target: await this.resolveTargetRef(args, ctx),
+            attributes: this.presentAttributes(args),
+        };
+    }
+    async presentDelete(args, ctx) {
+        return {
+            type: this.argType(args),
+            target: await this.resolveTargetRef(args, ctx),
+        };
+    }
+    async presentLink(args, ctx) {
+        return {
+            type: this.argType(args),
+            target: await this.resolveTargetRef(args, ctx),
+            relationship: typeof args.relationship === "string" ? args.relationship : "",
+            targets: await this.resolveLinkTargets(args, ctx),
+        };
+    }
+    async resolveLinkTargets(args, ctx) {
+        const entity = this.catalog.getEntityDetail(this.argType(args), ctx.userModuleIds);
+        const name = typeof args.relationship === "string" ? args.relationship : "";
+        const targetType = entity?.relationships.find((relationship) => relationship.name === name)?.targetType ?? (name || "record");
+        const refs = [];
+        for (const id of this.toIdList(args.targetIds))
+            refs.push(await this.resolveRef({ type: targetType, id, ctx }));
+        return refs;
+    }
+    presentAttributes(args) {
+        return args.fields && typeof args.fields === "object" ? { ...args.fields } : {};
+    }
 };
 exports.EntityWriteTools = EntityWriteTools;
 exports.EntityWriteTools = EntityWriteTools = EntityWriteTools_1 = __decorate([
@@ -472,6 +744,7 @@ exports.EntityWriteTools = EntityWriteTools = EntityWriteTools_1 = __decorate([
     __metadata("design:paramtypes", [graph_catalog_service_1.GraphCatalogService,
         entity_service_registry_1.EntityServiceRegistry,
         scope_guard_1.ScopeGuard,
-        tool_factory_1.ToolFactory])
+        tool_factory_1.ToolFactory,
+        blocknote_service_1.BlockNoteService])
 ], EntityWriteTools);
 //# sourceMappingURL=entity-write.tools.js.map