feat: guard raw parent context transport

Author: baum777

src/engagement/candidateBoundary.ts

@@ -2,6 +2,7 @@ import type { Mention } from "../poller/mentionsMapper.js";
 import type { CanonicalEvent, TriggerType } from "../canonical/types.js";
 import type { TimelineCandidate } from "./types.js";
 import { buildConversationParentRef, type ConversationBundle } from "./conversationBundle.js";
+import { buildRawConversationContextTokens } from "./conversationContextTransport.js";
 
 export interface RawTriggerInput {
   triggerType: "mention" | "timeline";
@@ -81,6 +82,7 @@ export function buildRawTriggerInputFromMention(
     parentRef: buildConversationParentRef({
       tweetId: parentTweetId,
       conversationId: mention.conversation_id ?? undefined,
+      authorId: mention.in_reply_to_user_id ?? undefined,
     }),
     discoveredAt: mention.created_at ?? "unknown",
     rawText: mention.text,
@@ -138,6 +140,7 @@ export function toCanonicalExecutionInput(
   const triggerType: TriggerType = candidate.triggerType === "mention" ? "mention" : "reply";
   const bundleContext =
     typeof bundle?.sourceMetadata?.context === "string" ? bundle.sourceMetadata.context : undefined;
+  const parentRef = bundle?.parentRef ?? candidate.parentRef;
 
   return {
     event_id: candidate.candidateId,
@@ -148,7 +151,8 @@ export function toCanonicalExecutionInput(
     text: candidate.normalizedText,
     parent_text: null,
     quoted_text: null,
-    conversation_context: [],
+    // Raw transport only: fixed tokens from direct parent fields, no interpretation.
+    conversation_context: buildRawConversationContextTokens({ parentRef }),
     cashtags: signals.cashtags,
     hashtags: signals.hashtags,
     urls: signals.urls,

src/engagement/conversationContextTransport.ts

@@ -0,0 +1,59 @@
+import type { ConversationParentRef } from "./conversationBundle.js";
+
+/**
+ * Raw conversation-context transport lives here and nowhere else.
+ * The contract is intentionally narrow: emit fixed, append-only tokens from
+ * already-available direct parent fields only.
+ */
+export const ALLOWED_CONVERSATION_CONTEXT_TOKEN_PREFIXES = [
+  "parent_tweet_id",
+  "parent_conversation_id",
+  "parent_author_id",
+] as const;
+
+/**
+ * Forbidden categories are policy reminders, not emitted tokens.
+ * They are listed here to keep transport raw and non-semantic.
+ */
+export const FORBIDDEN_CONVERSATION_CONTEXT_TOKEN_CATEGORIES = [
+  "dialogue quality judgments",
+  "participation judgments",
+  "risk judgments",
+  "social or intimacy judgments",
+  "relevance or scoring judgments",
+  "inferred debate state",
+  "inferred author role",
+  "inferred thread openness or closedness",
+  "semantic labels",
+] as const;
+
+export type AllowedConversationContextTokenPrefix =
+  (typeof ALLOWED_CONVERSATION_CONTEXT_TOKEN_PREFIXES)[number];
+
+export interface ConversationContextTransportInput {
+  parentRef?: ConversationParentRef;
+}
+
+export function buildRawConversationContextTokens(input: ConversationContextTransportInput): string[] {
+  const parentRef = input.parentRef;
+  if (!parentRef) {
+    return [];
+  }
+
+  const tokens: string[] = [];
+  if (parentRef.tweetId) {
+    tokens.push(`parent_tweet_id:${parentRef.tweetId}`);
+  }
+  if (parentRef.conversationId) {
+    tokens.push(`parent_conversation_id:${parentRef.conversationId}`);
+  }
+  if (parentRef.authorId) {
+    tokens.push(`parent_author_id:${parentRef.authorId}`);
+  }
+
+  return tokens;
+}
+
+export function isAllowedConversationContextToken(token: string): token is `${AllowedConversationContextTokenPrefix}:${string}` {
+  return ALLOWED_CONVERSATION_CONTEXT_TOKEN_PREFIXES.some((prefix) => token.startsWith(`${prefix}:`));
+}

src/worker/pollMentions.ts

@@ -340,6 +340,7 @@ export async function processCanonicalMention(
   const engagementCandidate = buildEngagementCandidate(rawTriggerInput);
   const conversationBundle = maybeBuildConversationBundle({
     candidate: engagementCandidate,
+    parentRef: rawTriggerInput.parentRef,
     sourceTweet: {
       tweetId: engagementCandidate.tweetId,
       conversationId: engagementCandidate.conversationId,

src/worker/pollTimelineEngagement.ts

@@ -371,6 +371,7 @@ export async function runTimelineEngagementIteration(): Promise<TimelineIteratio
         const engagementCandidate = buildEngagementCandidate(rawTriggerInput);
         const conversationBundle = maybeBuildConversationBundle({
           candidate: engagementCandidate,
+          parentRef: rawTriggerInput.parentRef,
           sourceTweet: {
             tweetId: engagementCandidate.tweetId,
             conversationId: engagementCandidate.conversationId,

tests/engagement/candidateBoundary.test.ts

@@ -26,6 +26,7 @@ describe("candidateBoundary", () => {
     const candidate = buildEngagementCandidate(raw);
     const bundle = maybeBuildConversationBundle({
       candidate,
+      parentRef: raw.parentRef,
       sourceTweet: {
         tweetId: candidate.tweetId,
         conversationId: candidate.conversationId,
@@ -50,10 +51,16 @@ describe("candidateBoundary", () => {
     expect(candidate.parentRef?.tweetId).toBe("parent-mention-1");
     expect(bundle?.sourceTweet?.tweetId).toBe("mention-1");
     expect(bundle?.parentRef?.tweetId).toBe("parent-mention-1");
+    expect(bundle?.parentRef?.authorId).toBe("bot-1");
     expect(bundle?.authorContext?.authorHandle).toBe("Alice");
     expect(canonical.event_id).toBe("mention-1");
     expect(canonical.trigger_type).toBe("mention");
     expect(canonical.author_handle).toBe("@alice");
+    expect(canonical.conversation_context).toEqual([
+      "parent_tweet_id:parent-mention-1",
+      "parent_conversation_id:conv-1",
+      "parent_author_id:bot-1",
+    ]);
     expect(canonical.context).toBeUndefined();
   });
 
@@ -98,6 +105,7 @@ describe("candidateBoundary", () => {
     const candidate = buildEngagementCandidate(raw);
     const bundle = maybeBuildConversationBundle({
       candidate,
+      parentRef: raw.parentRef,
       sourceTweet: {
         tweetId: candidate.tweetId,
         conversationId: candidate.conversationId,
@@ -126,6 +134,10 @@ describe("candidateBoundary", () => {
     expect(canonical.event_id).toBe("timeline:tweet-1");
     expect(canonical.trigger_type).toBe("reply");
     expect(canonical.author_handle).toBe("@bob");
+    expect(canonical.conversation_context).toEqual([
+      "parent_tweet_id:parent-tweet-1",
+      "parent_conversation_id:conv-2",
+    ]);
     expect(canonical.context).toBeUndefined();
   });
 
@@ -154,6 +166,10 @@ describe("candidateBoundary", () => {
     expect(bundle?.parentRef?.tweetId).toBe("parent-2");
     expect(bundle?.authorContext?.authorId).toBe("author-3");
     expect(bundle?.sourceMetadata?.authorHandle).toBe("alice");
+    expect(toCanonicalExecutionInput(candidate, bundle).conversation_context).toEqual([
+      "parent_tweet_id:parent-2",
+      "parent_conversation_id:conv-3",
+    ]);
   });
 
   it("keeps the bundle sparse when no cheap parent hint is present", () => {
@@ -185,6 +201,7 @@ describe("candidateBoundary", () => {
     expect(candidate.parentRef).toBeUndefined();
     expect(bundle?.parentRef).toBeUndefined();
     expect(bundle?.sourceTweet?.tweetId).toBe("mention-3");
+    expect(toCanonicalExecutionInput(candidate, bundle).conversation_context).toEqual([]);
   });
 
   it("keeps mention discoveredAt conservative when created_at is missing", () => {

tests/engagement/conversationContextTransport.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from "vitest";
+import {
+  ALLOWED_CONVERSATION_CONTEXT_TOKEN_PREFIXES,
+  FORBIDDEN_CONVERSATION_CONTEXT_TOKEN_CATEGORIES,
+  buildRawConversationContextTokens,
+  isAllowedConversationContextToken,
+} from "../../src/engagement/conversationContextTransport.js";
+
+describe("conversationContextTransport", () => {
+  it("keeps the allowed token vocabulary small and raw", () => {
+    expect(ALLOWED_CONVERSATION_CONTEXT_TOKEN_PREFIXES).toEqual([
+      "parent_tweet_id",
+      "parent_conversation_id",
+      "parent_author_id",
+    ]);
+    expect(FORBIDDEN_CONVERSATION_CONTEXT_TOKEN_CATEGORIES).toContain("risk judgments");
+    expect(FORBIDDEN_CONVERSATION_CONTEXT_TOKEN_CATEGORIES).toContain("participation judgments");
+  });
+
+  it("emits only raw direct-parent transport tokens when parent fields are present", () => {
+    const tokens = buildRawConversationContextTokens({
+      parentRef: {
+        tweetId: "tweet-parent-1",
+        conversationId: "conv-parent-1",
+        authorId: "author-parent-1",
+      },
+    });
+
+    expect(tokens).toEqual([
+      "parent_tweet_id:tweet-parent-1",
+      "parent_conversation_id:conv-parent-1",
+      "parent_author_id:author-parent-1",
+    ]);
+    expect(tokens.every((token) => isAllowedConversationContextToken(token))).toBe(true);
+    expect(isAllowedConversationContextToken("thread_open:true")).toBe(false);
+    expect(isAllowedConversationContextToken("risk:high")).toBe(false);
+    expect(isAllowedConversationContextToken("author_type:researcher")).toBe(false);
+  });
+
+  it("stays sparse when no direct parent context is available", () => {
+    expect(buildRawConversationContextTokens({})).toEqual([]);
+    expect(buildRawConversationContextTokens({ parentRef: undefined })).toEqual([]);
+  });
+});

tests/integration/pipeline/mentionPipelineConsentFlow.test.ts

@@ -22,6 +22,7 @@ const buildRawTriggerInputMock = vi.fn((mention: Mention, source: "mentions" | "
         tweetId: mention.referenced_tweets?.find((ref) => ref.type === "replied_to" || ref.type === "quoted")
           ?.id,
         conversationId: mention.conversation_id ?? undefined,
+        authorId: mention.in_reply_to_user_id ?? undefined,
       }
     : undefined,
   discoveredAt: mention.created_at ?? new Date().toISOString(),
@@ -257,9 +258,15 @@ describe("mention pipeline consent flow", () => {
     expect(buildRawTriggerInputMock).toHaveBeenCalledTimes(1);
     expect(buildEngagementCandidateMock).toHaveBeenCalledTimes(1);
     expect(maybeBuildConversationBundleMock).toHaveBeenCalledTimes(1);
+    expect(maybeBuildConversationBundleMock.mock.calls[0]?.[0].parentRef).toMatchObject({
+      tweetId: "bot-1",
+      conversationId: "conv-1",
+      authorId: "bot-1",
+    });
     expect(maybeBuildConversationBundleMock.mock.calls[0]?.[0].candidate.parentRef).toMatchObject({
       tweetId: "bot-1",
       conversationId: "conv-1",
+      authorId: "bot-1",
     });
     expect(assembleSignalProfileMock).toHaveBeenCalledTimes(1);
     expect(toCanonicalExecutionInputMock).toHaveBeenCalledTimes(1);

tests/worker/pollTimelineEngagement.integration.test.ts

@@ -405,6 +405,9 @@ describe("timeline engagement worker", () => {
     expect(handleEventMock).toHaveBeenCalledTimes(1);
     expect(replyMock).toHaveBeenCalledTimes(1);
     expect(maybeBuildConversationBundleMock).toHaveBeenCalledTimes(1);
+    expect(maybeBuildConversationBundleMock.mock.calls[0]?.[0].parentRef).toMatchObject({
+      conversationId: "conv-1",
+    });
     expect(maybeBuildConversationBundleMock.mock.calls[0]?.[0].candidate.parentRef).toMatchObject({
       conversationId: "conv-1",
     });