Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions docs/contracts/catalog-field-consumer-2207.md
Original file line number Diff line number Diff line change
Expand Up @@ -136,3 +136,15 @@ Required consumer assertions, once gates allow implementation: exactly one descr
Concrete source-inspection anchors for gate3: `save_context_metadata` in Database `supabase/migrations/20260920040000_context_guests.sql` accepts supplied URL/topic; `complete_context_enrichment` in `20260923070000_context_enrichment_scope.sql` writes supplied source items and accepts results. These are starting points for reserved-family guards, not an exhaustive writer/grant audit. At this API pin, no `read_binding`, `reconcile_retention` or `stream_binding_proposal` call exists under `app/` or `lib/`. Gate5's actual raw-history consumer is `lib/sessions/chats/getSessionChatHandler.ts`, which selects saved message parts following session/chat authorization without the proposed per-field source check.

Next action: root/UI review this exact contract and schema ownership. Runtime work is blocked by selection origin, callable deployed authority and publication/history gates; document approval alone does not unblock a live implementation.

## History withholding source increment — November 19, 2026

The existing session-chat GET handler now calls the [retained-field history
gate](../../lib/sessions/chats/retained-field/README.md) with the authenticated
account and validated session/chat/database-message anchors. Until a reviewed
current-source transport and publication protocol exist, marked retained-field
messages are omitted in full, including sibling text/numeric projections and
metadata. This is a default-denied history consumer, not a positive authority
implementation or activation of the proposed producer. Legacy raw-report
messages and controls retain their existing behavior. It does not qualify other
disclosure paths or derive provenance for unmarked text in separate messages.
7 changes: 4 additions & 3 deletions lib/sessions/chats/__tests__/getSessionChatHandler.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -23,9 +23,10 @@ function makeReq(): NextRequest {
}

function mockValidated(chatOverrides: Parameters<typeof baseChatRow>[0] = {}) {
vi.mocked(validateGetSessionChatRequest).mockResolvedValue(
baseChatRow({ id: "chat_1", session_id: "sess_1", ...chatOverrides }),
);
vi.mocked(validateGetSessionChatRequest).mockResolvedValue({
chat: baseChatRow({ id: "chat_1", session_id: "sess_1", ...chatOverrides }),
actorAccountId: "actual-actor",
});
}

describe("getSessionChatHandler", () => {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,10 @@ beforeEach(() => {
mocks.from.mockImplementation(() => {
throw new Error("Unexpected storage access");
});
mocks.validate.mockResolvedValue(baseChatRow({ id: chatId, session_id: sessionId }));
mocks.validate.mockResolvedValue({
chat: baseChatRow({ id: chatId, session_id: sessionId }),
actorAccountId: "actual-actor",
});
});
afterEach(() => {
expect(fetch).not.toHaveBeenCalled();
Expand Down Expand Up @@ -82,9 +85,10 @@ it("preserves the saved UIMessage and streaming state", async () => {
role: "assistant",
parts: [{ type: "text", text: "Saved answer" }],
};
mocks.validate.mockResolvedValue(
baseChatRow({ id: chatId, session_id: sessionId, active_stream_id: "synthetic-run" }),
);
mocks.validate.mockResolvedValue({
chat: baseChatRow({ id: chatId, session_id: sessionId, active_stream_id: "synthetic-run" }),
actorAccountId: "actual-actor",
});
mockRead([{ parts: message }]);
const response = await request();
expect(response.status).toBe(200);
Expand Down
201 changes: 201 additions & 0 deletions lib/sessions/chats/__tests__/retainedFieldHistory.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,201 @@
import { beforeEach, afterEach, expect, it, vi } from "vitest";
import { NextRequest } from "next/server";
import { baseSessionRow } from "@/lib/sessions/__tests__/baseSessionRow";
import { baseChatRow } from "@/lib/sessions/__tests__/baseChatRow";
import type { Tables } from "@/types/database.types";
import * as disclosure from "@/lib/sessions/chats/retained-field/readRetainedFieldDisclosure";
import { GET } from "@/app/api/sessions/[sessionId]/chats/[chatId]/route";

const mocks = vi.hoisted(() => ({
auth: vi.fn(),
sessions: vi.fn(),
chats: vi.fn(),
messages: vi.fn(),
}));
vi.mock("@/lib/auth/validateAuthContext", () => ({ validateAuthContext: mocks.auth }));
vi.mock("@/lib/supabase/sessions/selectSessions", () => ({ selectSessions: mocks.sessions }));
vi.mock("@/lib/supabase/chats/selectChats", () => ({ selectChats: mocks.chats }));
vi.mock("@/lib/supabase/chat_messages/selectChatMessages", () => ({
selectChatMessages: mocks.messages,
}));
vi.mock("@/lib/sessions/chats/patchSessionChatHandler", () => ({
patchSessionChatHandler: vi.fn(),
}));
vi.mock("@/lib/sessions/chats/deleteSessionChatHandler", () => ({
deleteSessionChatHandler: vi.fn(),
}));

const companion = {
type: "data-retained-field-snapshot",
capability: "retained-field-companion/1",
data: {
fieldContext: {
contract: "catalog-retained-field-projection/1",
items: [{ value: { amount: 987654321 } }],
},
surface: { schemaVersion: 1, fallbackText: "PRIVATE DERIVED 987654321" },
},
};
const legacy = {
id: "legacy",
role: "assistant",
parts: [
{
type: "data-catalog-snapshot",
data: { schemaVersion: 1, title: "Legacy report", controls: { sort: "streams" } },
},
{ type: "text", text: "Legacy answer" },
],
};
function row(parts: unknown, id = "retained"): Tables<"chat_messages"> {
return {
id,
chat_id: "chat_1",
role: "assistant",
parts: parts as Tables<"chat_messages">["parts"],
created_at: "2026-11-19T00:00:00Z",
};
}
function request() {
return GET(new NextRequest("https://fixture.invalid/api/sessions/sess_1/chats/chat_1"), {
params: Promise.resolve({ sessionId: "sess_1", chatId: "chat_1" }),
});
}
beforeEach(() => {
vi.restoreAllMocks();
vi.clearAllMocks();
vi.stubGlobal(
"fetch",
vi.fn(() => {
throw new Error("NETWORK FORBIDDEN");
}),
);
mocks.auth.mockResolvedValue({ accountId: "actual-actor", orgId: null, authToken: "synthetic" });
mocks.sessions.mockResolvedValue([baseSessionRow({ account_id: "actual-actor" })]);
mocks.chats.mockResolvedValue([baseChatRow()]);
});
afterEach(() => {
expect(fetch).not.toHaveBeenCalled();
vi.unstubAllGlobals();
});
it("withholds whole retained messages including sibling text, numeric tables and metadata, preserving legacy order", async () => {
const retained = {
id: "retained",
role: "assistant",
metadata: { summary: "PRIVATE DERIVED 987654321" },
parts: [
{ type: "text", text: "PRIVATE DERIVED 987654321" },
companion,
{ type: "data-table", data: { rows: [[987654321]] } },
],
};
mocks.messages.mockResolvedValue([
row(legacy, "legacy"),
row(retained),
row({ ...legacy, id: "after" }, "after"),
]);
const response = await request();
expect(response.status).toBe(200);
const body = await response.json();
expect(body.messages).toEqual([legacy, { ...legacy, id: "after" }]);
expect(JSON.stringify(body)).not.toContain("987654321");
expect(response.headers.get("Cache-Control")).toBe("private, no-store");
});
it.each([
{ ...companion, capability: "unknown-version" },
{ type: "data-retained-field-snapshot", data: null },
{ capability: "retained-field-companion/1", data: {} },
{ data: { fieldContext: { contract: "catalog-retained-field-projection/1" } } },
Comment thread
cubic-dev-ai[bot] marked this conversation as resolved.
Resolved
{ mode: "retained_field" },
])(
"withholds malformed or unsupported family members without relying on successful schema parsing: %j",
async part => {
mocks.messages.mockResolvedValue([
row({
id: "retained",
role: "assistant",
parts: [{ type: "text", text: "PRIVATE DERIVED" }, part],
}),
]);
expect((await (await request()).json()).messages).toEqual([]);
},
);
it("also withholds legacy array-shaped stored parts when they contain the new family", async () => {
mocks.messages.mockResolvedValue([row([{ type: "text", text: "PRIVATE DERIVED" }, companion])]);
expect((await (await request()).json()).messages).toEqual([]);
});
it("cached ready, successful preparation and local disclosure flags never permit history disclosure", async () => {
mocks.messages.mockResolvedValue([
row({
id: "retained",
role: "assistant",
state: "ready",
preparation: "ready",
disclosure: "available",
parts: [companion],
}),
]);
expect((await (await request()).json()).messages).toEqual([]);
});
it("preserves legacy text even when it mentions retained fields", async () => {
const message = {
id: "normal",
role: "assistant",
parts: [{ type: "text", text: "Explain data-retained-field-snapshot" }],
};
mocks.messages.mockResolvedValue([row(message)]);
expect((await (await request()).json()).messages).toEqual([message]);
});
it("does not read history for a different authenticated actor", async () => {
mocks.auth.mockResolvedValue({ accountId: "wrong-actor", orgId: null, authToken: "synthetic" });
expect((await request()).status).toBe(403);
expect(mocks.messages).not.toHaveBeenCalled();
});

it.each(["unavailable", "withdrawn", "stale", "error", "ready"])(
"denies the whole message for injected current-boundary result %s (including unsupported states)",
async state => {
const stored = {
id: "spoofed-message",
accountId: "forged-owner",
sessionId: "other-session",
chatId: "other-chat",
role: "assistant",
parts: [companion, { type: "text", text: "PRIVATE DERIVED" }],
};
const read = vi
.spyOn(disclosure, "readRetainedFieldDisclosure")
.mockResolvedValue({ state } as never);
mocks.messages.mockResolvedValue([row(stored, "database-message-id")]);
const body = await (await request()).json();
expect(body.messages).toEqual([]);
expect(read).toHaveBeenCalledExactlyOnceWith(
{
actorAccountId: "actual-actor",
sessionId: "sess_1",
chatId: "chat_1",
messageId: "database-message-id",
},
stored,
);
expect(JSON.stringify(body)).not.toContain("forged-owner");
},
);
it("withholds every projection on a thrown current-source error without retry or diagnostics", async () => {
const read = vi
.spyOn(disclosure, "readRetainedFieldDisclosure")
.mockRejectedValue(new Error("PRIVATE AUTHORITY ERROR"));
mocks.messages.mockResolvedValue([
row({ id: "retained", parts: [companion, { type: "text", text: "PRIVATE DERIVED" }] }),
row(legacy, "legacy"),
]);
const response = await request();
expect((await response.json()).messages).toEqual([legacy]);
expect(read).toHaveBeenCalledTimes(1);
});
it("does not invoke current-field authority for legacy reports or text", async () => {
const read = vi.spyOn(disclosure, "readRetainedFieldDisclosure");
mocks.messages.mockResolvedValue([row(legacy)]);
expect((await (await request()).json()).messages).toEqual([legacy]);
expect(read).not.toHaveBeenCalled();
});
Original file line number Diff line number Diff line change
Expand Up @@ -143,8 +143,9 @@ describe("validateGetSessionChatRequest", () => {
const res = await validateGetSessionChatRequest(makeReq(), "sess_1", "chat_1");
expect(res).not.toBeInstanceOf(NextResponse);
if (!(res instanceof NextResponse)) {
expect(res.id).toBe("chat_1");
expect(res.session_id).toBe("sess_1");
expect(res.chat.id).toBe("chat_1");
expect(res.actorAccountId).toBe(accountId);
expect(res.chat.session_id).toBe("sess_1");
}
expect(selectSessions).toHaveBeenCalledWith({ id: "sess_1" });
expect(selectChats).toHaveBeenCalledWith({ id: "chat_1" });
Expand Down
18 changes: 12 additions & 6 deletions lib/sessions/chats/getSessionChatHandler.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ import { getCorsHeaders } from "@/lib/networking/getCorsHeaders";
import { toChatResponse } from "@/lib/sessions/toChatResponse";
import { validateGetSessionChatRequest } from "@/lib/sessions/chats/validateGetSessionChatRequest";
import { selectChatMessages } from "@/lib/supabase/chat_messages/selectChatMessages";
import { filterRetainedFieldHistory } from "./retained-field/filterRetainedFieldHistory";

export interface SessionChatResponse {
chat: ReturnType<typeof toChatResponse>;
Expand All @@ -17,7 +18,8 @@ export interface SessionChatResponse {
* persisted UI message stream — enough for both initial render and
* in-tab refresh.
*
* `messages` is the raw `parts` JSON for each row (chat messages are
* Retained-field messages are withheld as a whole until current-source disclosure
* is implemented. Other `messages` retain the raw `parts` JSON (chat messages are
* stored as the full UIMessage; the caller deserializes back into
* its UIMessage type).
*
Expand All @@ -31,10 +33,11 @@ export async function getSessionChatHandler(
sessionId: string,
chatId: string,
): Promise<NextResponse> {
const chat = await validateGetSessionChatRequest(request, sessionId, chatId);
if (chat instanceof NextResponse) {
return chat;
const validated = await validateGetSessionChatRequest(request, sessionId, chatId);
if (validated instanceof NextResponse) {
return validated;
}
const { chat, actorAccountId } = validated;

const messages = await selectChatMessages({ chatId, orderBy: { createdAt: "asc" } });
if (messages === null) return errorResponse("Failed to load messages", 500);
Expand All @@ -43,8 +46,11 @@ export async function getSessionChatHandler(
{
chat: toChatResponse(chat),
isStreaming: chat.active_stream_id !== null,
messages: messages.map(row => row.parts),
messages: await filterRetainedFieldHistory(
{ actorAccountId, sessionId: chat.session_id, chatId: chat.id },
messages,
),
} satisfies SessionChatResponse,
{ status: 200, headers: getCorsHeaders() },
{ status: 200, headers: { ...getCorsHeaders(), "Cache-Control": "private, no-store" } },
);
}
64 changes: 64 additions & 0 deletions lib/sessions/chats/retained-field/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
# Retained-field history withholding (2207)

The existing GET `/api/sessions/{sessionId}/chats/{chatId}` now invokes this gate
before serializing saved messages. It does not activate retained-field production
or grant disclosure. The current-authority boundary has no implementation and
returns unavailable. There is deliberately no positive release branch, including
for an unexpected or cached `ready` value.

## Actual call graph

`route.GET` → `getSessionChatHandler` → `validateGetSessionChatRequest`
(authenticated account, session ownership, chat membership) → `selectChatMessages`
→ `filterRetainedFieldHistory` → `hasRetainedFieldContent` →
`readRetainedFieldDisclosure` → omission of the entire marked message.

The validator returns the actual authenticated account separately from the chat.
The gate passes that account, validated session/chat IDs and database message ID;
none comes from the saved message's claimed owner, workspace, actor or anchors.
The saved content remains untrusted input to any future authority implementation.
No workspace authority is inferred from session ownership.

`persistAssistantMessage` stores a full AI SDK UIMessage in `chat_messages.parts`.
Removing only its companion would leak sibling text, tables or metadata. The gate
therefore omits the whole stored message. Legacy array-shaped parts are inspected
as well. Unrelated messages retain their original values and order. A successful
response is explicitly private/no-store; empty filtered history remains a 200.
Existing auth and storage error behavior is preserved.

## Reserved family and limits

The proposed App envelope is `data-retained-field-snapshot` with capability
`retained-field-companion/1`, holding the unchanged schema-v1 surface alongside
`catalog-retained-field-projection/1`. Detection examines structured discriminants
throughout the saved JSON, including malformed payloads and unknown versions in
these reserved families. It also recognizes structured `mode: retained_field`.
It does not parse text, infer numeric meaning or extend schema-v1. This is a deny
classifier, not an admission schema or producer negotiation implementation.

This default-denied source integration intentionally withholds even a legitimate
historical retained-field message. Current-source read and publication locking,
exact selection/method/projection validation, batch authorization and a reviewed
transport are still required before any positive branch can be added. A callback,
local flag or successful earlier computation cannot replace them.

The boundary never fetches latest, re-keys, retains, expands, calls a provider or
falls back to legacy raw-report authority. No SQL, grants, flags or routes are
introduced. Frozen API1291/Database143 consumers are not imported or modified.

This qualifies this GET history consumer only. It cannot identify unmarked prose
in a separate message as derived, revoke an already delivered client object, or
qualify initial-send/replay/export/model inputs and other history endpoints. Those
paths and a provenance-preserving producer remain separate activation gates.

## Negative acceptance

The route tests invoke the real GET, handler, validator and gate with synthetic
auth/storage boundaries, prohibit network access and verify whole-message removal,
mixed text/numeric projections, malformed/unsupported family markers, stored ready
and local disclosure flags, real actor/anchor propagation, thrown failure with no
retry, and unchanged legacy reports/controls. Injected withdrawn/stale/ready states
are adversarial boundary results, not claims of actual SQL withdrawal qualification.
No authenticated production/history request is executed.

Run `pnpm exec vitest run lib/sessions/chats/__tests__`.
Loading
Loading