@ghostpaw/affinity 0.1.4 → 0.1.6

package/dist/index.cjs

@@ -1454,8 +1454,8 @@ function searchContacts(db, query, filters, options) {
     GROUP BY c.id
   `;
   const rows = db.prepare(sql).all(
-    ...params,
     normalizedPattern,
+    ...params,
     pattern,
     pattern,
     normalizedPattern
@@ -6443,12 +6443,43 @@ var manageAttributeTool = defineAffinityTool({
 });
 
 // src/tools/manage_commitment_tool.ts
+function normalizeParticipant(p) {
+  let contactId = p.contactId;
+  if (contactId === void 0 && p.contact != null) {
+    const loc = p.contact;
+    contactId = loc.contactId;
+  }
+  const result = {
+    contactId,
+    role: p.role
+  };
+  if (p.directionality !== void 0) {
+    result.directionality = p.directionality;
+  }
+  return result;
+}
+function ensureOwnerParticipates(db, participants) {
+  const ownerId = findOwnerContactId(db);
+  if (ownerId === null) return participants;
+  if (participants.some((p) => p.contactId === ownerId)) return participants;
+  return [{ contactId: ownerId, role: "actor" }, ...participants];
+}
+function prepareParticipants(db, raw) {
+  return ensureOwnerParticipates(db, raw.map(normalizeParticipant));
+}
 function manageCommitmentToolHandler(db, input) {
   return withToolHandling(() => {
     if (input.action === "record") {
+      const patched = {
+        ...input.input,
+        participants: prepareParticipants(
+          db,
+          input.input.participants
+        )
+      };
       return mutationToolResult(
         "record",
-        recordCommitment(db, input.input),
+        recordCommitment(db, patched),
         "commitment"
       );
     }
@@ -6466,7 +6497,7 @@ function manageCommitmentToolHandler(db, input) {
 }
 var manageCommitmentTool = defineAffinityTool({
   name: manageCommitmentToolName,
-  description: "Record or resolve one commitment such as a promise or agreement.",
+  description: "Record or resolve one commitment such as a promise or agreement. The owner contact is auto-injected into participants if missing.",
   whenToUse: "Use this when the work is specifically about a commitment lifecycle rather than a general event.",
   whenNotToUse: "Do not use this for ordinary interactions or direct relationship state changes.",
   sideEffects: "writes_state",
@@ -6484,10 +6515,42 @@ var manageCommitmentTool = defineAffinityTool({
   inputSchema: objectSchema(
     {
       action: enumSchema("Operation to perform.", ["record", "resolve"]),
-      input: {
-        type: "object",
-        description: "Commitment payload. Required when action=record."
-      },
+      input: objectSchema(
+        {
+          commitmentType: enumSchema("Promise or agreement.", [
+            "promise",
+            "agreement"
+          ]),
+          occurredAt: integerSchema(
+            "When the commitment was made, Unix timestamp in milliseconds."
+          ),
+          summary: stringSchema("Commitment summary. Must be non-empty."),
+          significance: integerSchema("Commitment significance from 1 to 10."),
+          dueAt: integerSchema("Optional due timestamp."),
+          participants: arraySchema(
+            objectSchema(
+              {
+                contactId: integerSchema(
+                  "Participant contact id. The owner contact MUST be included."
+                ),
+                role: stringSchema("Participant role."),
+                directionality: stringSchema("Optional directionality.")
+              },
+              ["contactId", "role"]
+            ),
+            "Participant list. Must be non-empty and include the owner contact."
+          ),
+          now: integerSchema("Optional timestamp override.")
+        },
+        [
+          "commitmentType",
+          "occurredAt",
+          "summary",
+          "significance",
+          "participants"
+        ],
+        "Commitment payload. Required when action=record."
+      ),
       commitmentEventId: integerSchema(
         "Commitment event id. Required when action=resolve."
       ),
@@ -6644,6 +6707,43 @@ var manageContactTool = defineAffinityTool({
 });
 
 // src/tools/manage_date_anchor_tool.ts
+function contactLocatorSchema4(description) {
+  return {
+    type: "object",
+    properties: {
+      contactId: integerSchema("Exact contact id."),
+      identity: objectSchema(
+        {
+          type: stringSchema("Identity type."),
+          value: stringSchema("Identity value.")
+        },
+        ["type", "value"],
+        "Contact identity locator."
+      )
+    },
+    description
+  };
+}
+function linkLocatorSchema3(description) {
+  return {
+    type: "object",
+    properties: {
+      linkId: integerSchema("Exact link id."),
+      endpoints: objectSchema(
+        {
+          fromContactId: integerSchema("From contact id."),
+          toContactId: integerSchema("To contact id."),
+          kind: stringSchema("Optional link kind."),
+          role: stringSchema("Optional link role."),
+          isStructural: booleanSchema("Optional structural discriminator.")
+        },
+        ["fromContactId", "toContactId"],
+        "Endpoint-based link locator."
+      )
+    },
+    description
+  };
+}
 function resolveDateAnchorTarget(db, target) {
   if (target.kind === "contact") {
     const contact = resolveContactLocator(db, target.contact, "target.contact");
@@ -6709,17 +6809,65 @@ var manageDateAnchorTool = defineAffinityTool({
   inputSchema: objectSchema(
     {
       action: enumSchema("Operation to perform.", ["add", "revise", "remove"]),
-      input: {
-        type: "object",
-        description: "Date anchor payload. Required when action=add."
-      },
+      input: objectSchema(
+        {
+          target: objectSchema(
+            {
+              kind: enumSchema("Target kind.", ["contact", "link"]),
+              contact: contactLocatorSchema4(
+                "Contact locator. Required when kind=contact. Provide contactId or identity."
+              ),
+              link: linkLocatorSchema3(
+                "Link locator. Required when kind=link. Provide linkId or endpoints."
+              )
+            },
+            ["kind"],
+            "Date-anchor target."
+          ),
+          recurrenceKind: enumSchema("Recurrence kind.", [
+            "birthday",
+            "anniversary",
+            "renewal",
+            "memorial",
+            "custom_yearly"
+          ]),
+          anchorMonth: integerSchema("Anchor month, 1\u201312."),
+          anchorDay: integerSchema("Anchor day, 1\u201331 (validated per month)."),
+          summary: stringSchema("Summary. Must be non-empty."),
+          significance: integerSchema("Significance from 1 to 10."),
+          now: integerSchema("Optional timestamp override."),
+          force: booleanSchema("Whether to bypass duplicate checks.")
+        },
+        [
+          "target",
+          "recurrenceKind",
+          "anchorMonth",
+          "anchorDay",
+          "summary",
+          "significance"
+        ],
+        "Date anchor payload. Required when action=add."
+      ),
       anchorEventId: integerSchema(
         "Anchor event id. Required when action=revise or remove."
       ),
-      patch: {
-        type: "object",
-        description: "Anchor patch. Required when action=revise."
-      },
+      patch: objectSchema(
+        {
+          recurrenceKind: enumSchema("Optional recurrence kind.", [
+            "birthday",
+            "anniversary",
+            "renewal",
+            "memorial",
+            "custom_yearly"
+          ]),
+          anchorMonth: integerSchema("Optional month, 1\u201312."),
+          anchorDay: integerSchema("Optional day, 1\u201331."),
+          summary: stringSchema("Optional summary."),
+          significance: integerSchema("Optional significance, 1\u201310.")
+        },
+        [],
+        "Anchor patch. Required when action=revise."
+      ),
       options: objectSchema(
         {
           now: integerSchema("Optional timestamp."),
@@ -6921,7 +7069,7 @@ function verifyIdentity(db, identityId, verifiedAt) {
 }
 
 // src/tools/manage_identity_tool.ts
-function contactLocatorSchema4(description) {
+function contactLocatorSchema5(description) {
   return {
     type: "object",
     properties: {
@@ -7000,7 +7148,7 @@ var manageIdentityTool = defineAffinityTool({
         "verify",
         "remove"
       ]),
-      contact: contactLocatorSchema4(
+      contact: contactLocatorSchema5(
         "Target contact. Required when action=add. Provide contactId or identity."
       ),
       input: objectSchema(
@@ -7040,7 +7188,7 @@ var manageIdentityTool = defineAffinityTool({
 });
 
 // src/tools/manage_relationship_tool.ts
-function contactLocatorSchema5(description) {
+function contactLocatorSchema6(description) {
   return {
     type: "object",
     properties: {
@@ -7057,7 +7205,7 @@ function contactLocatorSchema5(description) {
     description
   };
 }
-function linkLocatorSchema3(description) {
+function linkLocatorSchema4(description) {
   return {
     type: "object",
     properties: {
@@ -7089,10 +7237,15 @@ function manageRelationshipToolHandler(db, input) {
         if (!to.ok) {
           return to.result;
         }
+        const merged = {
+          ...input.input,
+          ...input.kind !== void 0 && input.input?.kind === void 0 ? { kind: input.kind } : {},
+          ...input.role !== void 0 && input.input?.role === void 0 ? { role: input.role } : {}
+        };
         return mutationToolResult(
           "seed_social_link",
           seedSocialLink(db, {
-            ...input.input,
+            ...merged,
             fromContactId: from.value.id,
             toContactId: to.value.id
           }),
@@ -7130,10 +7283,15 @@ function manageRelationshipToolHandler(db, input) {
         if (!to.ok) {
           return to.result;
         }
+        const merged = {
+          ...input.input,
+          ...input.kind !== void 0 && input.input?.kind === void 0 ? { kind: input.kind } : {},
+          ...input.role !== void 0 && input.input?.role === void 0 ? { role: input.role } : {}
+        };
         return mutationToolResult(
           "set_structural_tie",
           setStructuralTie(db, {
-            ...input.input,
+            ...merged,
             fromContactId: from.value.id,
             toContactId: to.value.id
           }),
@@ -7167,7 +7325,9 @@ var manageRelationshipTool = defineAffinityTool({
     action: "Which relationship action to perform.",
     from: "Source contact locator for actions that create or set links.",
     to: "Destination contact locator for actions that create or set links.",
-    input: "Action-specific creation payload.",
+    input: "Action-specific creation payload (alternative to top-level kind/role).",
+    kind: "Link kind for seed_social_link or set_structural_tie. Can be passed here or inside input.",
+    role: "Optional role for seed_social_link or set_structural_tie. Can be passed here or inside input.",
     link: "Target link locator for existing-link actions.",
     bond: "Replacement bond text or null.",
     state: "Replacement link state.",
@@ -7184,17 +7344,23 @@ var manageRelationshipTool = defineAffinityTool({
         "set_structural_tie",
         "remove_structural_tie"
       ]),
-      from: contactLocatorSchema5(
+      from: contactLocatorSchema6(
         "Source contact. Required when action=seed_social_link or set_structural_tie. Provide contactId or identity."
       ),
-      to: contactLocatorSchema5(
+      to: contactLocatorSchema6(
         "Target contact. Required when action=seed_social_link or set_structural_tie. Provide contactId or identity."
       ),
+      kind: stringSchema(
+        "Link kind. Required for seed_social_link and set_structural_tie. Can be passed here or inside input. For seed_social_link: personal, family, professional, romantic, care, service, observed, other_relational. For set_structural_tie: works_at, manages, member_of, married_to, partner_of, parent_of, child_of, sibling_of, friend_of, client_of, vendor_of, reports_to, belongs_to, other_structural."
+      ),
+      role: stringSchema(
+        "Optional role for seed_social_link or set_structural_tie. Can be passed here or inside input."
+      ),
       input: {
         type: "object",
-        description: "Payload for seed_social_link or set_structural_tie. Shape depends on action."
+        description: "Full payload for seed_social_link or set_structural_tie. Alternative to top-level kind/role."
       },
-      link: linkLocatorSchema3(
+      link: linkLocatorSchema4(
         "Target link. Required when action=revise_bond, override_state, or remove_structural_tie. Provide linkId or endpoints."
       ),
       bond: nullableStringSchema(
@@ -7223,7 +7389,7 @@ var manageRelationshipTool = defineAffinityTool({
 });
 
 // src/tools/merge_contacts_tool.ts
-function contactLocatorSchema6(description) {
+function contactLocatorSchema7(description) {
   return {
     type: "object",
     properties: {
@@ -7280,10 +7446,10 @@ var mergeContactsTool = defineAffinityTool({
   outputDescription: "Returns the merge receipt with rewired entities and affected-link information.",
   inputSchema: objectSchema(
     {
-      winner: contactLocatorSchema6(
+      winner: contactLocatorSchema7(
         "Winner contact. Provide contactId or identity."
       ),
-      loser: contactLocatorSchema6(
+      loser: contactLocatorSchema7(
         "Loser contact. Provide contactId or identity."
       ),
       reasonSummary: stringSchema("Optional merge reason."),
@@ -7296,31 +7462,64 @@ var mergeContactsTool = defineAffinityTool({
 });
 
 // src/tools/record_event_tool.ts
+function normalizeParticipant2(p) {
+  let contactId = p.contactId;
+  if (contactId === void 0 && p.contact != null) {
+    const loc = p.contact;
+    contactId = loc.contactId;
+  }
+  const result = {
+    contactId,
+    role: p.role
+  };
+  if (p.directionality !== void 0) {
+    result.directionality = p.directionality;
+  }
+  return result;
+}
+function ensureOwnerParticipates2(db, participants) {
+  const ownerId = findOwnerContactId(db);
+  if (ownerId === null) return participants;
+  if (participants.some((p) => p.contactId === ownerId)) return participants;
+  return [{ contactId: ownerId, role: "actor" }, ...participants];
+}
+function prepareParticipants2(db, raw, injectOwner) {
+  const normalized = raw.map(normalizeParticipant2);
+  return injectOwner ? ensureOwnerParticipates2(db, normalized) : normalized;
+}
 function recordEventToolHandler(db, input) {
   return withToolHandling(() => {
+    const patched = {
+      ...input.input,
+      participants: prepareParticipants2(
+        db,
+        input.input.participants,
+        input.kind !== "observation"
+      )
+    };
     switch (input.kind) {
       case "interaction":
         return mutationToolResult(
           "interaction",
-          recordInteraction(db, input.input),
+          recordInteraction(db, patched),
           "event"
         );
       case "observation":
         return mutationToolResult(
           "observation",
-          recordObservation(db, input.input),
+          recordObservation(db, patched),
           "event"
         );
       case "milestone":
         return mutationToolResult(
           "milestone",
-          recordMilestone(db, input.input),
+          recordMilestone(db, patched),
           "event"
         );
       case "transaction":
         return mutationToolResult(
           "transaction",
-          recordTransaction(db, input.input),
+          recordTransaction(db, patched),
           "event"
         );
     }
@@ -7328,7 +7527,7 @@ function recordEventToolHandler(db, input) {
 }
 var recordEventTool = defineAffinityTool({
   name: recordEventToolName,
-  description: "Record one social event such as an interaction, observation, milestone, or transaction.",
+  description: "Record one social event such as an interaction, observation, milestone, or transaction. For interactions, milestones, and transactions the owner contact is auto-injected into participants if missing. Observations may omit the owner when recording third-party evidence.",
   whenToUse: "Use this when you are capturing something that happened in the relationship graph.",
   whenNotToUse: "Do not use this for commitments, date anchors, or direct relationship state overrides.",
   sideEffects: "writes_state",
@@ -7348,10 +7547,53 @@ var recordEventTool = defineAffinityTool({
         "milestone",
         "transaction"
       ]),
-      input: {
-        type: "object",
-        description: "Event payload. Shape depends on kind. Interaction events require a `type` subtype; others do not. Always required."
-      }
+      input: objectSchema(
+        {
+          type: enumSchema(
+            "Interaction subtype. Required when kind=interaction, omit otherwise.",
+            [
+              "conversation",
+              "activity",
+              "gift",
+              "support",
+              "conflict",
+              "correction"
+            ]
+          ),
+          occurredAt: integerSchema(
+            "When the event occurred, Unix timestamp in milliseconds."
+          ),
+          summary: stringSchema("Event summary. Must be non-empty."),
+          significance: integerSchema("Event significance from 1 to 10."),
+          participants: arraySchema(
+            objectSchema(
+              {
+                contactId: integerSchema(
+                  "Participant contact id. The owner contact MUST be included."
+                ),
+                role: enumSchema("Participant role.", [
+                  "actor",
+                  "recipient",
+                  "subject",
+                  "observer",
+                  "mentioned"
+                ]),
+                directionality: enumSchema("Optional directionality.", [
+                  "owner_initiated",
+                  "other_initiated",
+                  "mutual",
+                  "observed"
+                ])
+              },
+              ["contactId", "role"]
+            ),
+            "Participant list. Must be non-empty and include the owner contact."
+          ),
+          now: integerSchema("Optional timestamp override.")
+        },
+        ["occurredAt", "summary", "significance", "participants"],
+        "Event payload. Always required. Interaction events also require `type`."
+      )
     },
     ["kind", "input"],
     "Record one social event."
@@ -7378,7 +7620,7 @@ function buildChartOptions(input) {
     ...input.contactIds === void 0 ? {} : { contactIds: input.contactIds }
   };
 }
-function contactLocatorSchema7(description) {
+function contactLocatorSchema8(description) {
   return {
     type: "object",
     properties: {
@@ -7395,7 +7637,7 @@ function contactLocatorSchema7(description) {
     description
   };
 }
-function linkLocatorSchema4(description) {
+function linkLocatorSchema5(description) {
   return {
     type: "object",
     properties: {
@@ -7814,8 +8056,8 @@ var reviewAffinityTool = defineAffinityTool({
         "graph.chart",
         "merges.history"
       ]),
-      contact: contactLocatorSchema7("Optional target contact locator."),
-      link: linkLocatorSchema4("Optional target link locator."),
+      contact: contactLocatorSchema8("Optional target contact locator."),
+      link: linkLocatorSchema5("Optional target link locator."),
       contactIds: arraySchema(
         integerSchema("Contact id."),
         "Optional contact-id subset."

package/dist/index.d.cts

@@ -1362,7 +1362,9 @@ type ManageRelationshipToolInput = {
     action: "seed_social_link";
     from: ContactLocator;
     to: ContactLocator;
-    input: Omit<SeedSocialLinkInput, "fromContactId" | "toContactId">;
+    input?: Omit<SeedSocialLinkInput, "fromContactId" | "toContactId">;
+    kind?: string;
+    role?: string;
 } | {
     action: "revise_bond";
     link: LinkLocator;
@@ -1377,7 +1379,9 @@ type ManageRelationshipToolInput = {
     action: "set_structural_tie";
     from: ContactLocator;
     to: ContactLocator;
-    input: Omit<SetStructuralTieInput, "fromContactId" | "toContactId">;
+    input?: Omit<SetStructuralTieInput, "fromContactId" | "toContactId">;
+    kind?: string;
+    role?: string;
 } | {
     action: "remove_structural_tie";
     link: LinkLocator;

package/dist/index.d.ts

@@ -1362,7 +1362,9 @@ type ManageRelationshipToolInput = {
     action: "seed_social_link";
     from: ContactLocator;
     to: ContactLocator;
-    input: Omit<SeedSocialLinkInput, "fromContactId" | "toContactId">;
+    input?: Omit<SeedSocialLinkInput, "fromContactId" | "toContactId">;
+    kind?: string;
+    role?: string;
 } | {
     action: "revise_bond";
     link: LinkLocator;
@@ -1377,7 +1379,9 @@ type ManageRelationshipToolInput = {
     action: "set_structural_tie";
     from: ContactLocator;
     to: ContactLocator;
-    input: Omit<SetStructuralTieInput, "fromContactId" | "toContactId">;
+    input?: Omit<SetStructuralTieInput, "fromContactId" | "toContactId">;
+    kind?: string;
+    role?: string;
 } | {
     action: "remove_structural_tie";
     link: LinkLocator;

package/dist/index.js

@@ -1452,8 +1452,8 @@ function searchContacts(db, query, filters, options) {
     GROUP BY c.id
   `;
   const rows = db.prepare(sql).all(
-    ...params,
     normalizedPattern,
+    ...params,
     pattern,
     pattern,
     normalizedPattern
@@ -6441,12 +6441,43 @@ var manageAttributeTool = defineAffinityTool({
 });
 
 // src/tools/manage_commitment_tool.ts
+function normalizeParticipant(p) {
+  let contactId = p.contactId;
+  if (contactId === void 0 && p.contact != null) {
+    const loc = p.contact;
+    contactId = loc.contactId;
+  }
+  const result = {
+    contactId,
+    role: p.role
+  };
+  if (p.directionality !== void 0) {
+    result.directionality = p.directionality;
+  }
+  return result;
+}
+function ensureOwnerParticipates(db, participants) {
+  const ownerId = findOwnerContactId(db);
+  if (ownerId === null) return participants;
+  if (participants.some((p) => p.contactId === ownerId)) return participants;
+  return [{ contactId: ownerId, role: "actor" }, ...participants];
+}
+function prepareParticipants(db, raw) {
+  return ensureOwnerParticipates(db, raw.map(normalizeParticipant));
+}
 function manageCommitmentToolHandler(db, input) {
   return withToolHandling(() => {
     if (input.action === "record") {
+      const patched = {
+        ...input.input,
+        participants: prepareParticipants(
+          db,
+          input.input.participants
+        )
+      };
       return mutationToolResult(
         "record",
-        recordCommitment(db, input.input),
+        recordCommitment(db, patched),
         "commitment"
       );
     }
@@ -6464,7 +6495,7 @@ function manageCommitmentToolHandler(db, input) {
 }
 var manageCommitmentTool = defineAffinityTool({
   name: manageCommitmentToolName,
-  description: "Record or resolve one commitment such as a promise or agreement.",
+  description: "Record or resolve one commitment such as a promise or agreement. The owner contact is auto-injected into participants if missing.",
   whenToUse: "Use this when the work is specifically about a commitment lifecycle rather than a general event.",
   whenNotToUse: "Do not use this for ordinary interactions or direct relationship state changes.",
   sideEffects: "writes_state",
@@ -6482,10 +6513,42 @@ var manageCommitmentTool = defineAffinityTool({
   inputSchema: objectSchema(
     {
       action: enumSchema("Operation to perform.", ["record", "resolve"]),
-      input: {
-        type: "object",
-        description: "Commitment payload. Required when action=record."
-      },
+      input: objectSchema(
+        {
+          commitmentType: enumSchema("Promise or agreement.", [
+            "promise",
+            "agreement"
+          ]),
+          occurredAt: integerSchema(
+            "When the commitment was made, Unix timestamp in milliseconds."
+          ),
+          summary: stringSchema("Commitment summary. Must be non-empty."),
+          significance: integerSchema("Commitment significance from 1 to 10."),
+          dueAt: integerSchema("Optional due timestamp."),
+          participants: arraySchema(
+            objectSchema(
+              {
+                contactId: integerSchema(
+                  "Participant contact id. The owner contact MUST be included."
+                ),
+                role: stringSchema("Participant role."),
+                directionality: stringSchema("Optional directionality.")
+              },
+              ["contactId", "role"]
+            ),
+            "Participant list. Must be non-empty and include the owner contact."
+          ),
+          now: integerSchema("Optional timestamp override.")
+        },
+        [
+          "commitmentType",
+          "occurredAt",
+          "summary",
+          "significance",
+          "participants"
+        ],
+        "Commitment payload. Required when action=record."
+      ),
       commitmentEventId: integerSchema(
         "Commitment event id. Required when action=resolve."
       ),
@@ -6642,6 +6705,43 @@ var manageContactTool = defineAffinityTool({
 });
 
 // src/tools/manage_date_anchor_tool.ts
+function contactLocatorSchema4(description) {
+  return {
+    type: "object",
+    properties: {
+      contactId: integerSchema("Exact contact id."),
+      identity: objectSchema(
+        {
+          type: stringSchema("Identity type."),
+          value: stringSchema("Identity value.")
+        },
+        ["type", "value"],
+        "Contact identity locator."
+      )
+    },
+    description
+  };
+}
+function linkLocatorSchema3(description) {
+  return {
+    type: "object",
+    properties: {
+      linkId: integerSchema("Exact link id."),
+      endpoints: objectSchema(
+        {
+          fromContactId: integerSchema("From contact id."),
+          toContactId: integerSchema("To contact id."),
+          kind: stringSchema("Optional link kind."),
+          role: stringSchema("Optional link role."),
+          isStructural: booleanSchema("Optional structural discriminator.")
+        },
+        ["fromContactId", "toContactId"],
+        "Endpoint-based link locator."
+      )
+    },
+    description
+  };
+}
 function resolveDateAnchorTarget(db, target) {
   if (target.kind === "contact") {
     const contact = resolveContactLocator(db, target.contact, "target.contact");
@@ -6707,17 +6807,65 @@ var manageDateAnchorTool = defineAffinityTool({
   inputSchema: objectSchema(
     {
       action: enumSchema("Operation to perform.", ["add", "revise", "remove"]),
-      input: {
-        type: "object",
-        description: "Date anchor payload. Required when action=add."
-      },
+      input: objectSchema(
+        {
+          target: objectSchema(
+            {
+              kind: enumSchema("Target kind.", ["contact", "link"]),
+              contact: contactLocatorSchema4(
+                "Contact locator. Required when kind=contact. Provide contactId or identity."
+              ),
+              link: linkLocatorSchema3(
+                "Link locator. Required when kind=link. Provide linkId or endpoints."
+              )
+            },
+            ["kind"],
+            "Date-anchor target."
+          ),
+          recurrenceKind: enumSchema("Recurrence kind.", [
+            "birthday",
+            "anniversary",
+            "renewal",
+            "memorial",
+            "custom_yearly"
+          ]),
+          anchorMonth: integerSchema("Anchor month, 1\u201312."),
+          anchorDay: integerSchema("Anchor day, 1\u201331 (validated per month)."),
+          summary: stringSchema("Summary. Must be non-empty."),
+          significance: integerSchema("Significance from 1 to 10."),
+          now: integerSchema("Optional timestamp override."),
+          force: booleanSchema("Whether to bypass duplicate checks.")
+        },
+        [
+          "target",
+          "recurrenceKind",
+          "anchorMonth",
+          "anchorDay",
+          "summary",
+          "significance"
+        ],
+        "Date anchor payload. Required when action=add."
+      ),
       anchorEventId: integerSchema(
         "Anchor event id. Required when action=revise or remove."
       ),
-      patch: {
-        type: "object",
-        description: "Anchor patch. Required when action=revise."
-      },
+      patch: objectSchema(
+        {
+          recurrenceKind: enumSchema("Optional recurrence kind.", [
+            "birthday",
+            "anniversary",
+            "renewal",
+            "memorial",
+            "custom_yearly"
+          ]),
+          anchorMonth: integerSchema("Optional month, 1\u201312."),
+          anchorDay: integerSchema("Optional day, 1\u201331."),
+          summary: stringSchema("Optional summary."),
+          significance: integerSchema("Optional significance, 1\u201310.")
+        },
+        [],
+        "Anchor patch. Required when action=revise."
+      ),
       options: objectSchema(
         {
           now: integerSchema("Optional timestamp."),
@@ -6919,7 +7067,7 @@ function verifyIdentity(db, identityId, verifiedAt) {
 }
 
 // src/tools/manage_identity_tool.ts
-function contactLocatorSchema4(description) {
+function contactLocatorSchema5(description) {
   return {
     type: "object",
     properties: {
@@ -6998,7 +7146,7 @@ var manageIdentityTool = defineAffinityTool({
         "verify",
         "remove"
       ]),
-      contact: contactLocatorSchema4(
+      contact: contactLocatorSchema5(
         "Target contact. Required when action=add. Provide contactId or identity."
       ),
       input: objectSchema(
@@ -7038,7 +7186,7 @@ var manageIdentityTool = defineAffinityTool({
 });
 
 // src/tools/manage_relationship_tool.ts
-function contactLocatorSchema5(description) {
+function contactLocatorSchema6(description) {
   return {
     type: "object",
     properties: {
@@ -7055,7 +7203,7 @@ function contactLocatorSchema5(description) {
     description
   };
 }
-function linkLocatorSchema3(description) {
+function linkLocatorSchema4(description) {
   return {
     type: "object",
     properties: {
@@ -7087,10 +7235,15 @@ function manageRelationshipToolHandler(db, input) {
         if (!to.ok) {
           return to.result;
         }
+        const merged = {
+          ...input.input,
+          ...input.kind !== void 0 && input.input?.kind === void 0 ? { kind: input.kind } : {},
+          ...input.role !== void 0 && input.input?.role === void 0 ? { role: input.role } : {}
+        };
         return mutationToolResult(
           "seed_social_link",
           seedSocialLink(db, {
-            ...input.input,
+            ...merged,
             fromContactId: from.value.id,
             toContactId: to.value.id
           }),
@@ -7128,10 +7281,15 @@ function manageRelationshipToolHandler(db, input) {
         if (!to.ok) {
           return to.result;
         }
+        const merged = {
+          ...input.input,
+          ...input.kind !== void 0 && input.input?.kind === void 0 ? { kind: input.kind } : {},
+          ...input.role !== void 0 && input.input?.role === void 0 ? { role: input.role } : {}
+        };
         return mutationToolResult(
           "set_structural_tie",
           setStructuralTie(db, {
-            ...input.input,
+            ...merged,
             fromContactId: from.value.id,
             toContactId: to.value.id
           }),
@@ -7165,7 +7323,9 @@ var manageRelationshipTool = defineAffinityTool({
     action: "Which relationship action to perform.",
     from: "Source contact locator for actions that create or set links.",
     to: "Destination contact locator for actions that create or set links.",
-    input: "Action-specific creation payload.",
+    input: "Action-specific creation payload (alternative to top-level kind/role).",
+    kind: "Link kind for seed_social_link or set_structural_tie. Can be passed here or inside input.",
+    role: "Optional role for seed_social_link or set_structural_tie. Can be passed here or inside input.",
     link: "Target link locator for existing-link actions.",
     bond: "Replacement bond text or null.",
     state: "Replacement link state.",
@@ -7182,17 +7342,23 @@ var manageRelationshipTool = defineAffinityTool({
         "set_structural_tie",
         "remove_structural_tie"
       ]),
-      from: contactLocatorSchema5(
+      from: contactLocatorSchema6(
         "Source contact. Required when action=seed_social_link or set_structural_tie. Provide contactId or identity."
       ),
-      to: contactLocatorSchema5(
+      to: contactLocatorSchema6(
         "Target contact. Required when action=seed_social_link or set_structural_tie. Provide contactId or identity."
       ),
+      kind: stringSchema(
+        "Link kind. Required for seed_social_link and set_structural_tie. Can be passed here or inside input. For seed_social_link: personal, family, professional, romantic, care, service, observed, other_relational. For set_structural_tie: works_at, manages, member_of, married_to, partner_of, parent_of, child_of, sibling_of, friend_of, client_of, vendor_of, reports_to, belongs_to, other_structural."
+      ),
+      role: stringSchema(
+        "Optional role for seed_social_link or set_structural_tie. Can be passed here or inside input."
+      ),
       input: {
         type: "object",
-        description: "Payload for seed_social_link or set_structural_tie. Shape depends on action."
+        description: "Full payload for seed_social_link or set_structural_tie. Alternative to top-level kind/role."
       },
-      link: linkLocatorSchema3(
+      link: linkLocatorSchema4(
         "Target link. Required when action=revise_bond, override_state, or remove_structural_tie. Provide linkId or endpoints."
       ),
       bond: nullableStringSchema(
@@ -7221,7 +7387,7 @@ var manageRelationshipTool = defineAffinityTool({
 });
 
 // src/tools/merge_contacts_tool.ts
-function contactLocatorSchema6(description) {
+function contactLocatorSchema7(description) {
   return {
     type: "object",
     properties: {
@@ -7278,10 +7444,10 @@ var mergeContactsTool = defineAffinityTool({
   outputDescription: "Returns the merge receipt with rewired entities and affected-link information.",
   inputSchema: objectSchema(
     {
-      winner: contactLocatorSchema6(
+      winner: contactLocatorSchema7(
         "Winner contact. Provide contactId or identity."
       ),
-      loser: contactLocatorSchema6(
+      loser: contactLocatorSchema7(
         "Loser contact. Provide contactId or identity."
       ),
       reasonSummary: stringSchema("Optional merge reason."),
@@ -7294,31 +7460,64 @@ var mergeContactsTool = defineAffinityTool({
 });
 
 // src/tools/record_event_tool.ts
+function normalizeParticipant2(p) {
+  let contactId = p.contactId;
+  if (contactId === void 0 && p.contact != null) {
+    const loc = p.contact;
+    contactId = loc.contactId;
+  }
+  const result = {
+    contactId,
+    role: p.role
+  };
+  if (p.directionality !== void 0) {
+    result.directionality = p.directionality;
+  }
+  return result;
+}
+function ensureOwnerParticipates2(db, participants) {
+  const ownerId = findOwnerContactId(db);
+  if (ownerId === null) return participants;
+  if (participants.some((p) => p.contactId === ownerId)) return participants;
+  return [{ contactId: ownerId, role: "actor" }, ...participants];
+}
+function prepareParticipants2(db, raw, injectOwner) {
+  const normalized = raw.map(normalizeParticipant2);
+  return injectOwner ? ensureOwnerParticipates2(db, normalized) : normalized;
+}
 function recordEventToolHandler(db, input) {
   return withToolHandling(() => {
+    const patched = {
+      ...input.input,
+      participants: prepareParticipants2(
+        db,
+        input.input.participants,
+        input.kind !== "observation"
+      )
+    };
     switch (input.kind) {
       case "interaction":
         return mutationToolResult(
           "interaction",
-          recordInteraction(db, input.input),
+          recordInteraction(db, patched),
           "event"
         );
       case "observation":
         return mutationToolResult(
           "observation",
-          recordObservation(db, input.input),
+          recordObservation(db, patched),
           "event"
         );
       case "milestone":
         return mutationToolResult(
           "milestone",
-          recordMilestone(db, input.input),
+          recordMilestone(db, patched),
           "event"
         );
       case "transaction":
         return mutationToolResult(
           "transaction",
-          recordTransaction(db, input.input),
+          recordTransaction(db, patched),
           "event"
         );
     }
@@ -7326,7 +7525,7 @@ function recordEventToolHandler(db, input) {
 }
 var recordEventTool = defineAffinityTool({
   name: recordEventToolName,
-  description: "Record one social event such as an interaction, observation, milestone, or transaction.",
+  description: "Record one social event such as an interaction, observation, milestone, or transaction. For interactions, milestones, and transactions the owner contact is auto-injected into participants if missing. Observations may omit the owner when recording third-party evidence.",
   whenToUse: "Use this when you are capturing something that happened in the relationship graph.",
   whenNotToUse: "Do not use this for commitments, date anchors, or direct relationship state overrides.",
   sideEffects: "writes_state",
@@ -7346,10 +7545,53 @@ var recordEventTool = defineAffinityTool({
         "milestone",
         "transaction"
       ]),
-      input: {
-        type: "object",
-        description: "Event payload. Shape depends on kind. Interaction events require a `type` subtype; others do not. Always required."
-      }
+      input: objectSchema(
+        {
+          type: enumSchema(
+            "Interaction subtype. Required when kind=interaction, omit otherwise.",
+            [
+              "conversation",
+              "activity",
+              "gift",
+              "support",
+              "conflict",
+              "correction"
+            ]
+          ),
+          occurredAt: integerSchema(
+            "When the event occurred, Unix timestamp in milliseconds."
+          ),
+          summary: stringSchema("Event summary. Must be non-empty."),
+          significance: integerSchema("Event significance from 1 to 10."),
+          participants: arraySchema(
+            objectSchema(
+              {
+                contactId: integerSchema(
+                  "Participant contact id. The owner contact MUST be included."
+                ),
+                role: enumSchema("Participant role.", [
+                  "actor",
+                  "recipient",
+                  "subject",
+                  "observer",
+                  "mentioned"
+                ]),
+                directionality: enumSchema("Optional directionality.", [
+                  "owner_initiated",
+                  "other_initiated",
+                  "mutual",
+                  "observed"
+                ])
+              },
+              ["contactId", "role"]
+            ),
+            "Participant list. Must be non-empty and include the owner contact."
+          ),
+          now: integerSchema("Optional timestamp override.")
+        },
+        ["occurredAt", "summary", "significance", "participants"],
+        "Event payload. Always required. Interaction events also require `type`."
+      )
     },
     ["kind", "input"],
     "Record one social event."
@@ -7376,7 +7618,7 @@ function buildChartOptions(input) {
     ...input.contactIds === void 0 ? {} : { contactIds: input.contactIds }
   };
 }
-function contactLocatorSchema7(description) {
+function contactLocatorSchema8(description) {
   return {
     type: "object",
     properties: {
@@ -7393,7 +7635,7 @@ function contactLocatorSchema7(description) {
     description
   };
 }
-function linkLocatorSchema4(description) {
+function linkLocatorSchema5(description) {
   return {
     type: "object",
     properties: {
@@ -7812,8 +8054,8 @@ var reviewAffinityTool = defineAffinityTool({
         "graph.chart",
         "merges.history"
       ]),
-      contact: contactLocatorSchema7("Optional target contact locator."),
-      link: linkLocatorSchema4("Optional target link locator."),
+      contact: contactLocatorSchema8("Optional target contact locator."),
+      link: linkLocatorSchema5("Optional target link locator."),
       contactIds: arraySchema(
         integerSchema("Contact id."),
         "Optional contact-id subset."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghostpaw/affinity",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Relationship intelligence and social CRM model for Node.js — SQLite, zero dependencies, with a built-in LLM tool facade",
   "license": "MIT",
   "author": {