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: 11 additions & 1 deletion lib/context/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,17 @@ and `readiness`, and adds bounded Markdown `text`, `text_characters`, `request_i
versions. `max_characters` independently bounds evidence JSON and rendered text;
it is not a cap on the entire response including metadata. Documents are omitted
whole to fit the limit; evidence is never cut mid-claim. A missing topic may mean
absent, ineligible or over-budget evidence.
absent, ineligible or over-budget evidence. `input_manifest.freshness` reports the
oldest and newest retrieval timestamps across every dated source of the selected
documents, the documents with no dated source, and each selected document's own
`oldestRetrievedAt`/`newestRetrievedAt`; every document section in `text` ends with a
`Retrieved:` line (one timestamp, `<oldest> to <newest>` when its sources differ, or
`unknown`) and never a source location. Freshness is reported, not enforced: no age
limit drops evidence yet. `compilerVersion` remains `context-brief-v1` because `save_context_brief`
pins that value and compares the document manifest exactly; freshness is additive.
The response contract makes `freshness` optional so historical snapshots remain readable
without adding dates or recompiling their saved text. New compilations include the field;
unknown retrieval bounds are null, and retrieval times are not publication/event dates.

These are attributed evidence briefs for downstream work, not generated creative
proposals or finished outreach. `brief` is read-only and recompilation can reflect
Expand Down
137 changes: 137 additions & 0 deletions lib/context/__tests__/briefFreshnessContract.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,137 @@
import { expect, it, vi } from "vitest";
import { processContextOperation } from "../processContextOperation";
import {
contextBriefResponseSchema,
contextBriefSnapshotSchema,
} from "../contracts/contextBriefResponseSchemas";
vi.mock("../authorizeContextOwner", () => ({
authorizeContextOwner: vi.fn(async (ownerId: string) => ({ ownerId })),
}));
const owner = "11111111-1111-4111-8111-111111111111";
const request = "22222222-2222-4222-8222-222222222222";
const subject = "33333333-3333-4333-8333-333333333333";
const documentId = "44444444-4444-4444-8444-444444444444";
const resultId = "55555555-5555-4555-8555-555555555555";
const source = "66666666-6666-4666-8666-666666666666";
const snapshotId = "77777777-7777-4777-8777-777777777777";
const date = "2026-10-20T12:00:00.000Z";
const fixture = () => {
let saved: unknown;
const dispatch = vi.fn();
const rpc = vi.fn(async (name: string, args: Record<string, unknown>) => {
if (name === "read_context_request")
return {
id: request,
owner_id: owner,
status: "completed",
output: { subjectIds: [subject] },
};
if (name === "read_context_documents")
return [
{
id: documentId,
resultId,
ownerId: owner,
subjectId: subject,
topic: "song_summary",
version: 1,
status: "accepted",
evidenceKind: "observation",
coverage: "partial",
text: "Quiet piano; interpretation remains tentative.",
sourceVersionIds: [source],
sources: [
{ versionId: source, url: "https://private.example.test/evidence", retrievedAt: date },
],
},
];
if (name === "save_context_brief")
return (saved = {
id: snapshotId,
state: "saved",
superseded: false,
purpose: "playlist_pitch",
created_at: date,
brief: args.p_snapshot,
});
if (name === "read_context_brief") return saved;
throw new Error(`Unexpected operation ${name}`);
});
return {
rpc,
dispatch,
setSaved(value: unknown) {
saved = value;
},
};
};
const input = { request_id: request, purpose: "playlist_pitch" };

it("validates real compile/save/read outputs without changing the exact storage document manifest", async () => {
const deps = fixture();
const compiled = await processContextOperation(owner, { action: "brief", ...input }, deps);
const brief = contextBriefResponseSchema.parse(compiled);
expect(brief.input_manifest).toMatchObject({
compilerVersion: "context-brief-v1",
freshness: {
oldestRetrievedAt: date,
newestRetrievedAt: date,
documentsWithoutRetrievalDate: [],
documents: [{ documentId, oldestRetrievedAt: date, newestRetrievedAt: date }],
},
});
expect(brief.input_manifest.documents).toEqual([
{
documentId,
resultId,
subjectId: subject,
topic: "song_summary",
version: 1,
sourceVersionIds: [source],
},
]);
expect(brief.text).toContain(`Retrieved: ${date}`);
expect(brief.text).toContain("Included evidence: 1 document.");
expect(JSON.stringify(brief.input_manifest)).not.toContain("private.example.test");
const saved = await processContextOperation(
owner,
{ action: "save_brief", ...input, idempotency_key: "freshness-contract" },
deps,
);
expect(contextBriefSnapshotSchema.parse(saved)).toEqual(saved);
const reopened = await processContextOperation(
owner,
{ action: "read_brief", brief_id: snapshotId },
deps,
);
expect(contextBriefSnapshotSchema.parse(reopened)).toEqual(saved);
expect(deps.dispatch).not.toHaveBeenCalled();
});

it("reads legacy snapshots with no freshness without inventing dates or recompiling", async () => {
const deps = fixture();
const compiled = (await processContextOperation(owner, { action: "brief", ...input }, deps)) as {
input_manifest: Record<string, unknown>;
};
delete compiled.input_manifest.freshness;
const saved = {
id: snapshotId,
state: "saved",
superseded: false,
purpose: "playlist_pitch",
created_at: date,
brief: compiled,
};
deps.setSaved(saved);
deps.rpc.mockClear();
const reopened = await processContextOperation(
owner,
{ action: "read_brief", brief_id: snapshotId },
deps,
);
expect(contextBriefSnapshotSchema.parse(reopened)).toEqual({ snapshot: saved });
expect(deps.rpc).toHaveBeenCalledExactlyOnceWith("read_context_brief", {
p_owner: owner,
p_brief: snapshotId,
});
});
31 changes: 31 additions & 0 deletions lib/context/__tests__/compileContextBrief.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -261,3 +261,34 @@ it.each([
expect(result.input_manifest.documents).toHaveLength(result.documents.length);
expect(result.text).toContain(text);
});

it("reports unknown freshness without failing when source rows are absent or undated", () => {
const brief = compileContextBrief({
...input,
purpose: "playlist_pitch",
documents: [
document("song-a", "song_summary"),
{ ...document("song-a", "catalog_metadata"), sources: [] },
{
...document("artist", "artist_research"),
sources: [{ versionId: "artist:artist_research:source", retrievedAt: "yesterday" }],
},
],
});
expect(brief.input_manifest.compilerVersion).toBe("context-brief-v1");
expect(brief.input_manifest.freshness).toEqual({
oldestRetrievedAt: null,
newestRetrievedAt: null,
documentsWithoutRetrievalDate: [
"song-a:catalog_metadata",
"song-a:song_summary",
"artist:artist_research",
],
documents: [
{ documentId: "song-a:catalog_metadata", oldestRetrievedAt: null, newestRetrievedAt: null },
{ documentId: "song-a:song_summary", oldestRetrievedAt: null, newestRetrievedAt: null },
{ documentId: "artist:artist_research", oldestRetrievedAt: null, newestRetrievedAt: null },
],
});
expect(brief.text.match(/Retrieved: unknown/g)).toHaveLength(3);
});
Loading
Loading