From fed40adcc66408d5d2595dbdff9b2a1c98c73519 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Wed, 18 Nov 2026 07:04:25 -0500 Subject: [PATCH 1/5] Prepare bounded single-video context evidence from retained fixtures --- lib/context/video/README.md | 63 ++++ .../prepareContextVideoEvidence.test.ts | 279 ++++++++++++++++++ .../video/contextVideoEvidenceSchema.ts | 133 +++++++++ .../video/prepareContextVideoEvidence.ts | 107 +++++++ 4 files changed, 582 insertions(+) create mode 100644 lib/context/video/README.md create mode 100644 lib/context/video/__tests__/prepareContextVideoEvidence.test.ts create mode 100644 lib/context/video/contextVideoEvidenceSchema.ts create mode 100644 lib/context/video/prepareContextVideoEvidence.ts diff --git a/lib/context/video/README.md b/lib/context/video/README.md new file mode 100644 index 000000000..6c6d50bae --- /dev/null +++ b/lib/context/video/README.md @@ -0,0 +1,63 @@ +# Single-video evidence projection — CE15 fixture slice + +`prepareContextVideoEvidence` prepares retained evidence for one saved YouTube +request using injected, authorized readers. It returns the existing +`ContextEnrichmentModule` and `ContextEnrichmentResult` shapes plus eligible saved +`ContextBriefDocument` artist-research documents. It performs no provider call, +media fetch, identity write, persistence, credit reservation or settlement. + +This is the missing evidence projection for app#2131, not another ingestion action. +The separate open API#1019 saves a video locator only. Current public ingestion +still rejects YouTube execution. This module is not registered with HTTP, MCP, +workers or the enrichment scheduler. CE14, source retention/identity acceptance, +Database topic support, approved spending and hosted/native validation remain +separate prerequisites for a production connection. + +## Contract + +The actor and owner come from the shared authenticated operation. Readers must +return the selected owner's retained request/evidence and current authorized +artist documents. The function authorizes before reads and again before return; +it validates owner/request/video bindings, source-version membership, exact media +versions, distinct video/recording/artist identities and every analyzed range. +Source-backed identity is supplied by the reader, never inferred from a channel, +title or description. Validation of references is not independent identity proof. +An unresolved recording remains unresolved and triggers no artist-document read. + +Uploader/channel, observed performers and credited artists are separate fields. +Live/remix/dubbed/unknown versions, missing captions, multilingual segments and +disjoint analyzed ranges remain explicit. Available metadata survives unavailable +captions or analysis. A reader exception remains an error; the adapter does not +hide authorization/storage failures as missing media. Readers represent known +module unavailability explicitly in the evidence envelope. + +The sole projected topic is `video_narrative`, on the video subject, with +interpretation evidence and partial coverage. Captions are retained video evidence, +never original full-song lyrics. Visual observations and interpretations remain +separate within each range. This never updates `lyrics`, `song_summary`, +`artwork_branding` or `artist_brand`. Declared sources preserve original version +IDs, retrieval times and media versions; full input evidence remains in the module +fingerprint input rather than an abbreviated source summary. Prior provider cost +is unknown, not zero; preparing a projection does not authorize or settle spend. + +Matched credited artists allow reuse of current accepted, source-backed +`artist_research` documents through the existing selection helper. Wrong-owner, +unrelated, withdrawn, creative-proposal, unknown-coverage and missing-result +records are excluded. Returned documents retain their original IDs, result IDs, +versions, text and source-version sets. No generation fallback exists. The reader +is responsible for current-version/access checks; selection is not a replacement +for those checks or an atomic snapshot guarantee. + +No new brief recipe or snapshot field is introduced. Existing brief schema-v1, +full saved snapshots, six-key document manifests and compiler behavior remain +unchanged. `video_narrative` is currently outside the existing brief recipes; +future authorized integration must supply persisted documents through the shared +path rather than relabel this output as song/artist evidence or fabricate IDs. + +## Local verification + +Focused fixtures cover related artist reuse, label-channel attribution, alternate +versions, unresolved identity, multiple languages, partial ranges, unavailable +media, source/version and owner/request mismatch, revoked access and filtered +reuse. These demonstrate source behavior only; they do not establish collection, +Database acceptance, live accounting, ingestion or hosted availability. diff --git a/lib/context/video/__tests__/prepareContextVideoEvidence.test.ts b/lib/context/video/__tests__/prepareContextVideoEvidence.test.ts new file mode 100644 index 000000000..e71ed1dec --- /dev/null +++ b/lib/context/video/__tests__/prepareContextVideoEvidence.test.ts @@ -0,0 +1,279 @@ +import { expect, it, vi } from "vitest"; +import { prepareContextVideoEvidence } from "../prepareContextVideoEvidence"; +import type { ContextBriefDocument } from "../../selectContextDocuments"; + +const owner = "11111111-1111-4111-8111-111111111111"; +const requestId = "22222222-2222-4222-8222-222222222222"; +const videoSubject = "33333333-3333-4333-8333-333333333333"; +const artist = "44444444-4444-4444-8444-444444444444"; +const sourceId = "55555555-5555-4555-8555-555555555555"; +const recording = "66666666-6666-4666-8666-666666666666"; +const url = "https://www.youtube.com/watch?v=abcdefghijk"; +const document: ContextBriefDocument = { + id: "77777777-7777-4777-8777-777777777777", + resultId: recording, + ownerId: owner, + subjectId: artist, + topic: "artist_research", + version: 1, + status: "accepted", + evidenceKind: "observation", + text: "Previously accepted artist research", + sourceVersionIds: [sourceId], + coverage: "partial", +}; +function fixture() { + const evidence = { + requestId, + ownerId: owner, + videoSubjectId: videoSubject, + videoId: "abcdefghijk", + mediaVersion: "upload-v1", + durationSeconds: 180, + variant: "original", + title: "Fixture song video", + description: "Fixture description", + channel: { id: "label-channel", name: "Label uploader" }, + performers: [{ name: "Guest performer", sourceVersionIds: [sourceId] }], + identity: { + state: "matched", + recordingSubjectId: recording, + creditedArtists: [{ subjectId: artist, name: "Credited artist" }], + sourceVersionIds: [sourceId], + }, + sources: [ + { + versionId: sourceId, + videoId: "abcdefghijk", + mediaVersion: "upload-v1", + retrievedAt: "2026-11-18T05:00:00Z", + }, + ], + captions: { + state: "available", + sourceVersionIds: [sourceId], + segments: [ + { startSeconds: 0, endSeconds: 12, language: "es", text: "Synthetic caption" }, + { startSeconds: 20, endSeconds: 30, language: "en", text: "Another synthetic caption" }, + ], + }, + analysis: { + state: "available", + sourceVersionIds: [sourceId], + ranges: [ + { + startSeconds: 0, + endSeconds: 30, + observations: ["A figure crosses a room"], + interpretation: "The scene suggests departure", + }, + ], + }, + }; + const deps = { + authorize: vi.fn(async () => true), + readRequest: vi.fn(async () => ({ + id: requestId, + owner_id: owner, + created_by: owner, + input: { url }, + status: "partial", + })), + readEvidence: vi.fn(async () => evidence), + readArtistDocuments: vi.fn(async () => ({ + documents: [document], + withdrawnSourceVersionIds: [] as string[], + })), + }; + return { evidence, deps }; +} +const prepare = (deps: ReturnType["deps"]) => + prepareContextVideoEvidence(owner, owner, requestId, deps); + +it("projects one video using shared module/result shapes and reuses artist evidence unchanged", async () => { + const { deps } = fixture(); + const result = await prepare(deps); + expect(result.module).toMatchObject({ + topic: "video_narrative", + subjectId: videoSubject, + evidenceKind: "interpretation", + }); + expect(result.result).toMatchObject({ + coverage: "partial", + costUsd: null, + costStatus: "unknown", + }); + expect(result.result.content).toMatchObject({ + channel: { id: "label-channel" }, + identity: { creditedArtists: [{ subjectId: artist }] }, + originalSongLyrics: "not_established", + }); + expect(result.reusedArtistDocuments).toEqual([document]); + expect(deps.readArtistDocuments).toHaveBeenCalledWith(owner, [artist]); + expect(deps.authorize).toHaveBeenCalledTimes(2); + expect(JSON.stringify(result.module)).not.toContain('"topic":"artist_brand"'); +}); +it.each(["live", "remix", "dubbed", "unknown"])( + "preserves %s version and never promotes captions to original lyrics", + async variant => { + const { evidence, deps } = fixture(); + evidence.variant = variant; + const result = await prepare(deps); + expect(result.result.coverage).toBe("partial"); + expect(result.result.content).toMatchObject({ variant, originalSongLyrics: "not_established" }); + expect(result.module.topic).not.toBe("lyrics"); + }, +); +it("keeps unresolved identity separate from uploader and never requests artist research", async () => { + const { evidence, deps } = fixture(); + Object.assign(evidence, { identity: { state: "unresolved", reason: "Ambiguous recording" } }); + const result = await prepare(deps); + expect(result.result.content).toMatchObject({ identity: { state: "unresolved" } }); + expect(result.reusedArtistDocuments).toEqual([]); + expect(deps.readArtistDocuments).not.toHaveBeenCalled(); +}); +it("retains multilingual captions and exact disjoint analyzed ranges without claiming full coverage", async () => { + const { evidence, deps } = fixture(); + evidence.analysis.ranges.push({ + startSeconds: 90, + endSeconds: 100, + observations: ["A doorway"], + interpretation: "An uncertain ending", + }); + const result = await prepare(deps); + expect(result.result.content).toMatchObject({ + captions: evidence.captions, + analysis: evidence.analysis, + }); + expect(result.result.coverage).toBe("partial"); +}); +it("preserves metadata when captions and analysis are unavailable", async () => { + const { evidence, deps } = fixture(); + Object.assign(evidence, { + captions: { state: "missing", reason: "No captions" }, + analysis: { state: "unavailable", reason: "No analyzed frames" }, + }); + const result = await prepare(deps); + expect(result.result.content).toMatchObject({ + description: evidence.description, + captions: { state: "missing" }, + analysis: { state: "unavailable" }, + }); +}); +it.each(["ownerId", "requestId", "videoId"])( + "rejects wrong %s binding before reuse", + async field => { + const { evidence, deps } = fixture(); + Object.assign(evidence, { [field]: field === "videoId" ? "12345678901" : recording }); + await expect(prepare(deps)).rejects.toThrow(); + expect(deps.readArtistDocuments).not.toHaveBeenCalled(); + }, +); +it("rejects references outside retained source versions and mismatched media versions", async () => { + const { evidence, deps } = fixture(); + evidence.analysis.sourceVersionIds = [recording]; + await expect(prepare(deps)).rejects.toThrow(); + evidence.analysis.sourceVersionIds = [sourceId]; + evidence.sources[0].mediaVersion = "other-version"; + await expect(prepare(deps)).rejects.toThrow(); +}); +it("rejects an analyzed range outside the video", async () => { + const { evidence, deps } = fixture(); + evidence.analysis.ranges[0].endSeconds = 181; + await expect(prepare(deps)).rejects.toThrow(); +}); +it("excludes wrong-owner, wrong-artist, withdrawn and brand documents from reuse", async () => { + const { deps } = fixture(); + deps.readArtistDocuments.mockResolvedValue({ + documents: [ + { ...document, ownerId: recording }, + { ...document, subjectId: recording }, + { ...document, status: "withdrawn" }, + { ...document, topic: "artist_brand" }, + ], + withdrawnSourceVersionIds: [], + }); + expect((await prepare(deps)).reusedArtistDocuments).toEqual([]); + deps.readArtistDocuments.mockResolvedValue({ + documents: [document], + withdrawnSourceVersionIds: [sourceId], + }); + expect((await prepare(deps)).reusedArtistDocuments).toEqual([]); +}); +it("stops before evidence reads on denied access and rechecks before returning", async () => { + const { deps } = fixture(); + deps.authorize.mockRejectedValueOnce(new Error("Denied")); + await expect(prepare(deps)).rejects.toThrow("Denied"); + expect(deps.readEvidence).not.toHaveBeenCalled(); + deps.authorize.mockResolvedValueOnce(true).mockRejectedValueOnce(new Error("Revoked")); + await expect(prepare(deps)).rejects.toThrow("Revoked"); +}); +it("rejects cancelled requests and non-video input", async () => { + const { deps } = fixture(); + deps.readRequest.mockResolvedValueOnce({ + id: requestId, + owner_id: owner, + created_by: owner, + input: { url }, + status: "cancelled", + }); + await expect(prepare(deps)).rejects.toThrow(); + deps.readRequest.mockResolvedValueOnce({ + id: requestId, + owner_id: owner, + created_by: owner, + input: { url: "https://open.spotify.com/track/1234567890123456789012" }, + status: "partial", + }); + await expect(prepare(deps)).rejects.toThrow(); +}); + +it("reuses both credited collaborators without promoting their channel or performer to artist", async () => { + const { evidence, deps } = fixture(); + const collaborator = "88888888-8888-4888-8888-888888888888"; + evidence.identity.creditedArtists.push({ subjectId: collaborator, name: "Collaborator" }); + deps.readArtistDocuments.mockResolvedValue({ + documents: [document, { ...document, id: collaborator, subjectId: collaborator }], + withdrawnSourceVersionIds: [], + }); + const before = JSON.stringify(evidence); + const result = await prepare(deps); + expect(deps.readArtistDocuments).toHaveBeenCalledWith(owner, [artist, collaborator]); + expect(result.reusedArtistDocuments).toHaveLength(2); + expect(JSON.stringify(evidence)).toBe(before); +}); +it("preserves caption formatting and rejects empty interpretation", async () => { + const { evidence, deps } = fixture(); + evidence.captions.segments[0].text = " Synthetic\ncaption "; + expect((await prepare(deps)).result.content).toMatchObject({ + captions: { + segments: [expect.objectContaining({ text: " Synthetic\ncaption " }), expect.anything()], + }, + }); + evidence.analysis.ranges[0].interpretation = "\u200b "; + await expect(prepare(deps)).rejects.toThrow(); +}); +it("rejects video subject masquerading as an artist or recording", async () => { + const { evidence, deps } = fixture(); + evidence.identity.creditedArtists[0].subjectId = videoSubject; + await expect(prepare(deps)).rejects.toThrow(); +}); +it("does not hide errors from the retained-evidence reader", async () => { + const { deps } = fixture(); + deps.readEvidence.mockRejectedValue(new Error("Retention unavailable")); + await expect(prepare(deps)).rejects.toThrow("Retention unavailable"); + expect(deps.readArtistDocuments).not.toHaveBeenCalled(); +}); + +it("uses an existing shared source kind and exact media-version bytes", async () => { + const { evidence, deps } = fixture(); + expect((await prepare(deps)).module.sources).toEqual([ + { + url, + kind: "provider_metadata", + content: evidence.sources[0], + }, + ]); + evidence.sources[0].mediaVersion = " upload-v1 "; + await expect(prepare(deps)).rejects.toThrow(); +}); diff --git a/lib/context/video/contextVideoEvidenceSchema.ts b/lib/context/video/contextVideoEvidenceSchema.ts new file mode 100644 index 000000000..58273c989 --- /dev/null +++ b/lib/context/video/contextVideoEvidenceSchema.ts @@ -0,0 +1,133 @@ +import { z } from "zod"; + +const text = z + .string() + .min(1) + .max(4000) + .refine(value => /[^\s\p{Cf}\p{Default_Ignorable_Code_Point}]/u.test(value)); +const references = z + .array(z.uuid()) + .min(1) + .max(32) + .refine(ids => new Set(ids).size === ids.length); +const range = { + startSeconds: z.number().nonnegative().finite(), + endSeconds: z.number().positive().finite(), +}; +const unavailable = z.strictObject({ state: z.enum(["missing", "unavailable"]), reason: text }); + +/** Retained, authorized evidence supplied by an injected reader; never a public identity assertion. */ +export const contextVideoEvidenceSchema = z + .strictObject({ + requestId: z.uuid(), + ownerId: z.uuid(), + videoSubjectId: z.uuid(), + videoId: z.string().regex(/^[A-Za-z0-9_-]{11}$/), + mediaVersion: text, + durationSeconds: z.number().positive().finite().nullable(), + variant: z.enum(["original", "live", "remix", "dubbed", "unknown"]), + title: text, + description: z.string().max(20000), + channel: z.strictObject({ id: text, name: text }), + performers: z.array(z.strictObject({ name: text, sourceVersionIds: references })).max(50), + identity: z.discriminatedUnion("state", [ + z.strictObject({ state: z.literal("unresolved"), reason: text }), + z.strictObject({ + state: z.literal("matched"), + recordingSubjectId: z.uuid(), + creditedArtists: z + .array(z.strictObject({ subjectId: z.uuid(), name: text })) + .min(1) + .max(50), + sourceVersionIds: references, + }), + ]), + sources: z + .array( + z.strictObject({ + versionId: z.uuid(), + videoId: z.string(), + mediaVersion: text, + retrievedAt: z.iso.datetime(), + }), + ) + .min(1) + .max(32), + captions: z.union([ + unavailable, + z.strictObject({ + state: z.literal("available"), + sourceVersionIds: references, + segments: z + .array(z.strictObject({ ...range, language: z.string().min(1).max(100), text })) + .min(1) + .max(500), + }), + ]), + analysis: z.union([ + unavailable, + z.strictObject({ + state: z.literal("available"), + sourceVersionIds: references, + ranges: z + .array( + z.strictObject({ + ...range, + observations: z.array(text).min(1).max(50), + interpretation: text, + }), + ) + .min(1) + .max(100), + }), + ]), + }) + .superRefine((evidence, ctx) => { + const ids = new Set(evidence.sources.map(source => source.versionId)); + const references = [ + ...evidence.performers.flatMap(person => person.sourceVersionIds), + ...(evidence.identity.state === "matched" ? evidence.identity.sourceVersionIds : []), + ...(evidence.captions.state === "available" ? evidence.captions.sourceVersionIds : []), + ...(evidence.analysis.state === "available" ? evidence.analysis.sourceVersionIds : []), + ]; + const ranges = [ + ...(evidence.captions.state === "available" ? evidence.captions.segments : []), + ...(evidence.analysis.state === "available" ? evidence.analysis.ranges : []), + ]; + if ( + ids.size !== evidence.sources.length || + references.some(id => !ids.has(id)) || + evidence.sources.some( + source => + source.videoId !== evidence.videoId || source.mediaVersion !== evidence.mediaVersion, + ) + ) + ctx.addIssue({ + code: "custom", + message: "Video evidence requires exact retained source/version bindings", + }); + if ( + ranges.some( + range => + range.endSeconds <= range.startSeconds || + (evidence.durationSeconds !== null && range.endSeconds > evidence.durationSeconds), + ) + ) + ctx.addIssue({ code: "custom", message: "Invalid analyzed video range" }); + const identity = evidence.identity; + if ( + identity.state === "matched" && + (identity.recordingSubjectId === evidence.videoSubjectId || + identity.creditedArtists.some( + artist => + artist.subjectId === evidence.videoSubjectId || + artist.subjectId === identity.recordingSubjectId, + ) || + new Set(identity.creditedArtists.map(artist => artist.subjectId)).size !== + identity.creditedArtists.length) + ) + ctx.addIssue({ + code: "custom", + message: "Video, recording and credited artist identities must remain separate", + }); + }); diff --git a/lib/context/video/prepareContextVideoEvidence.ts b/lib/context/video/prepareContextVideoEvidence.ts new file mode 100644 index 000000000..a4badca22 --- /dev/null +++ b/lib/context/video/prepareContextVideoEvidence.ts @@ -0,0 +1,107 @@ +import { z } from "zod"; +import { parseContextUrl } from "../parseContextUrl"; +import { selectContextDocuments, type ContextBriefDocument } from "../selectContextDocuments"; +import type { ContextRequestRecord } from "../runContextRequest"; +import type { + ContextEnrichmentModule, + ContextEnrichmentResult, +} from "../enrichment/runContextEnrichment"; +import { contextVideoEvidenceSchema } from "./contextVideoEvidenceSchema"; + +type Dependencies = { + authorize: (actor: string, owner: string) => Promise; + readRequest: (owner: string, requestId: string) => Promise; + /** Must return retained evidence from authorized sources, never infer identity from the uploader. */ + readEvidence: (owner: string, requestId: string) => Promise; + readArtistDocuments: ( + owner: string, + artistSubjectIds: string[], + ) => Promise<{ + documents: ContextBriefDocument[]; + withdrawnSourceVersionIds: string[]; + }>; +}; + +/** Prepare one fixture-only video projection. No collection, persistence, accounting or public dispatch. */ +export async function prepareContextVideoEvidence( + actor: string, + owner: string, + requestId: string, + deps: Dependencies, +): Promise<{ + module: ContextEnrichmentModule; + result: ContextEnrichmentResult; + reusedArtistDocuments: ContextBriefDocument[]; +}> { + z.uuid().parse(owner); + z.uuid().parse(requestId); + await deps.authorize(actor, owner); + const request = await deps.readRequest(owner, requestId); + if ( + !request || + request.id !== requestId || + request.owner_id !== owner || + request.status === "cancelled" + ) + throw new Error("Video context request unavailable"); + const resource = parseContextUrl(request.input.url); + if (resource.provider !== "youtube") throw new Error("Single YouTube video required"); + const evidence = contextVideoEvidenceSchema.parse(await deps.readEvidence(owner, requestId)); + if ( + evidence.requestId !== requestId || + evidence.ownerId !== owner || + evidence.videoId !== resource.id + ) + throw new Error("Video evidence does not match the selected request"); + let reusedArtistDocuments: ContextBriefDocument[] = []; + if (evidence.identity.state === "matched") { + const subjectIds = evidence.identity.creditedArtists.map(artist => artist.subjectId); + const saved = await deps.readArtistDocuments(owner, subjectIds); + if (saved.documents.length > 1000 || saved.withdrawnSourceVersionIds.length > 32000) + throw new Error("Artist evidence exceeds bounded selection"); + reusedArtistDocuments = selectContextDocuments( + saved.documents.filter(doc => Boolean(doc.resultId)), + { + ownerId: owner, + subjectIds, + topics: ["artist_research"], + maxCharacters: 32000, + requiredCoverage: "partial", + withdrawnSourceVersionIds: saved.withdrawnSourceVersionIds, + }, + ).documents; + } + await deps.authorize(actor, owner); + const sources = evidence.sources.map(source => ({ + url: resource.url, + kind: "provider_metadata", + content: source, + })); + const module: ContextEnrichmentModule = { + key: "video-narrative-fixture-v1", + topic: "video_narrative", + subjectId: evidence.videoSubjectId, + provider: "retained-evidence", + model: "none", + evidenceKind: "interpretation", + input: evidence, + sources, + }; + const result: ContextEnrichmentResult = { + content: { + ...evidence, + originalSongLyrics: "not_established", + scope: "video_only", + artistBrand: "not_established", + }, + // No projection can establish original-song completeness, even with every video frame analyzed. + coverage: "partial", + costUsd: null, + costStatus: "unknown", + trace: { + method: "retained_video_projection", + sourceVersionIds: evidence.sources.map(source => source.versionId), + }, + }; + return { module, result, reusedArtistDocuments }; +} From b257f06c626fbe22bd4d6ff618b6723e3df21f14 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Wed, 18 Nov 2026 07:08:46 -0500 Subject: [PATCH 2/5] Compare video identity and source UUIDs case insensitively --- .../prepareContextVideoEvidence.test.ts | 27 +++++++++++++++++++ .../video/contextVideoEvidenceSchema.ts | 14 +++++----- 2 files changed, 34 insertions(+), 7 deletions(-) diff --git a/lib/context/video/__tests__/prepareContextVideoEvidence.test.ts b/lib/context/video/__tests__/prepareContextVideoEvidence.test.ts index e71ed1dec..ff714ed75 100644 --- a/lib/context/video/__tests__/prepareContextVideoEvidence.test.ts +++ b/lib/context/video/__tests__/prepareContextVideoEvidence.test.ts @@ -277,3 +277,30 @@ it("uses an existing shared source kind and exact media-version bytes", async () evidence.sources[0].mediaVersion = " upload-v1 "; await expect(prepare(deps)).rejects.toThrow(); }); + +it("rejects case aliases of the same video, recording or credited artist identity", async () => { + const { evidence, deps } = fixture(); + const mixedId = "abcdefab-abcd-4abc-8abc-abcdefabcdef"; + evidence.videoSubjectId = mixedId; + evidence.identity.creditedArtists[0].subjectId = mixedId.toUpperCase(); + await expect(prepare(deps)).rejects.toThrow(); + evidence.identity.creditedArtists[0].subjectId = artist; + evidence.identity.recordingSubjectId = mixedId.toUpperCase(); + await expect(prepare(deps)).rejects.toThrow(); + evidence.identity.recordingSubjectId = recording; + evidence.identity.creditedArtists = [ + { subjectId: mixedId, name: "One" }, + { subjectId: mixedId.toUpperCase(), name: "Duplicate" }, + ]; + evidence.videoSubjectId = videoSubject; + await expect(prepare(deps)).rejects.toThrow(); +}); +it("rejects duplicate retained source UUID aliases", async () => { + const { evidence, deps } = fixture(); + const mixedId = "abcdefab-abcd-4abc-8abc-abcdefabcdef"; + evidence.sources.push( + { ...evidence.sources[0], versionId: mixedId }, + { ...evidence.sources[0], versionId: mixedId.toUpperCase() }, + ); + await expect(prepare(deps)).rejects.toThrow(); +}); diff --git a/lib/context/video/contextVideoEvidenceSchema.ts b/lib/context/video/contextVideoEvidenceSchema.ts index 58273c989..767659130 100644 --- a/lib/context/video/contextVideoEvidenceSchema.ts +++ b/lib/context/video/contextVideoEvidenceSchema.ts @@ -9,7 +9,7 @@ const references = z .array(z.uuid()) .min(1) .max(32) - .refine(ids => new Set(ids).size === ids.length); + .refine(ids => new Set(ids.map(id => id.toLowerCase())).size === ids.length); const range = { startSeconds: z.number().nonnegative().finite(), endSeconds: z.number().positive().finite(), @@ -83,7 +83,7 @@ export const contextVideoEvidenceSchema = z ]), }) .superRefine((evidence, ctx) => { - const ids = new Set(evidence.sources.map(source => source.versionId)); + const ids = new Set(evidence.sources.map(source => source.versionId.toLowerCase())); const references = [ ...evidence.performers.flatMap(person => person.sourceVersionIds), ...(evidence.identity.state === "matched" ? evidence.identity.sourceVersionIds : []), @@ -96,7 +96,7 @@ export const contextVideoEvidenceSchema = z ]; if ( ids.size !== evidence.sources.length || - references.some(id => !ids.has(id)) || + references.some(id => !ids.has(id.toLowerCase())) || evidence.sources.some( source => source.videoId !== evidence.videoId || source.mediaVersion !== evidence.mediaVersion, @@ -117,13 +117,13 @@ export const contextVideoEvidenceSchema = z const identity = evidence.identity; if ( identity.state === "matched" && - (identity.recordingSubjectId === evidence.videoSubjectId || + (identity.recordingSubjectId.toLowerCase() === evidence.videoSubjectId.toLowerCase() || identity.creditedArtists.some( artist => - artist.subjectId === evidence.videoSubjectId || - artist.subjectId === identity.recordingSubjectId, + artist.subjectId.toLowerCase() === evidence.videoSubjectId.toLowerCase() || + artist.subjectId.toLowerCase() === identity.recordingSubjectId.toLowerCase(), ) || - new Set(identity.creditedArtists.map(artist => artist.subjectId)).size !== + new Set(identity.creditedArtists.map(artist => artist.subjectId.toLowerCase())).size !== identity.creditedArtists.length) ) ctx.addIssue({ From 1e6e6ba2617934aed9534495c528e1076dc26038 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Wed, 18 Nov 2026 07:09:46 -0500 Subject: [PATCH 3/5] Preserve UUID-equivalent saved artist reuse and withdrawals --- .../prepareContextVideoEvidence.test.ts | 21 ++++++++++++ .../video/prepareContextVideoEvidence.ts | 32 ++++++++++++------- 2 files changed, 42 insertions(+), 11 deletions(-) diff --git a/lib/context/video/__tests__/prepareContextVideoEvidence.test.ts b/lib/context/video/__tests__/prepareContextVideoEvidence.test.ts index ff714ed75..00bba2bb7 100644 --- a/lib/context/video/__tests__/prepareContextVideoEvidence.test.ts +++ b/lib/context/video/__tests__/prepareContextVideoEvidence.test.ts @@ -304,3 +304,24 @@ it("rejects duplicate retained source UUID aliases", async () => { ); await expect(prepare(deps)).rejects.toThrow(); }); + +it("reuses case-equivalent artist UUIDs without rewriting saved document references", async () => { + const { evidence, deps } = fixture(); + const mixedId = "abcdefab-abcd-4abc-8abc-abcdefabcdef"; + evidence.identity.creditedArtists[0].subjectId = mixedId.toUpperCase(); + const original = { ...document, subjectId: mixedId }; + deps.readArtistDocuments.mockResolvedValue({ + documents: [original], + withdrawnSourceVersionIds: [], + }); + expect((await prepare(deps)).reusedArtistDocuments).toEqual([original]); +}); +it("excludes source withdrawal case aliases", async () => { + const { deps } = fixture(); + const mixedId = "abcdefab-abcd-4abc-8abc-abcdefabcdef"; + deps.readArtistDocuments.mockResolvedValue({ + documents: [{ ...document, sourceVersionIds: [mixedId] }], + withdrawnSourceVersionIds: [mixedId.toUpperCase()], + }); + expect((await prepare(deps)).reusedArtistDocuments).toEqual([]); +}); diff --git a/lib/context/video/prepareContextVideoEvidence.ts b/lib/context/video/prepareContextVideoEvidence.ts index a4badca22..093eae273 100644 --- a/lib/context/video/prepareContextVideoEvidence.ts +++ b/lib/context/video/prepareContextVideoEvidence.ts @@ -59,17 +59,27 @@ export async function prepareContextVideoEvidence( const saved = await deps.readArtistDocuments(owner, subjectIds); if (saved.documents.length > 1000 || saved.withdrawnSourceVersionIds.length > 32000) throw new Error("Artist evidence exceeds bounded selection"); - reusedArtistDocuments = selectContextDocuments( - saved.documents.filter(doc => Boolean(doc.resultId)), - { - ownerId: owner, - subjectIds, - topics: ["artist_research"], - maxCharacters: 32000, - requiredCoverage: "partial", - withdrawnSourceVersionIds: saved.withdrawnSourceVersionIds, - }, - ).documents; + // Compare UUID identity canonically; return retained documents byte-for-byte unchanged. + const originals = new Map(); + for (const document of saved.documents.filter(doc => Boolean(doc.resultId))) { + originals.set( + { + ...document, + ownerId: document.ownerId.toLowerCase(), + subjectId: document.subjectId.toLowerCase(), + sourceVersionIds: document.sourceVersionIds.map(id => id.toLowerCase()), + }, + document, + ); + } + reusedArtistDocuments = selectContextDocuments([...originals.keys()], { + ownerId: owner.toLowerCase(), + subjectIds: subjectIds.map(id => id.toLowerCase()), + topics: ["artist_research"], + maxCharacters: 32000, + requiredCoverage: "partial", + withdrawnSourceVersionIds: saved.withdrawnSourceVersionIds.map(id => id.toLowerCase()), + }).documents.map(document => originals.get(document)!); } await deps.authorize(actor, owner); const sources = evidence.sources.map(source => ({ From d8648491d9eff77bf26caec1a6463dab8c5ee803 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Wed, 18 Nov 2026 07:19:51 -0500 Subject: [PATCH 4/5] Close video fixture review gaps in reader bindings and retained text --- .../prepareContextVideoEvidence.test.ts | 55 +++++++++++++++++++ .../video/contextVideoEvidenceSchema.ts | 11 +++- .../video/prepareContextVideoEvidence.ts | 44 +++++---------- .../video/selectContextVideoArtistResearch.ts | 31 +++++++++++ 4 files changed, 107 insertions(+), 34 deletions(-) create mode 100644 lib/context/video/selectContextVideoArtistResearch.ts diff --git a/lib/context/video/__tests__/prepareContextVideoEvidence.test.ts b/lib/context/video/__tests__/prepareContextVideoEvidence.test.ts index 00bba2bb7..62c7b7ced 100644 --- a/lib/context/video/__tests__/prepareContextVideoEvidence.test.ts +++ b/lib/context/video/__tests__/prepareContextVideoEvidence.test.ts @@ -111,6 +111,21 @@ it("projects one video using shared module/result shapes and reuses artist evide expect(result.reusedArtistDocuments).toEqual([document]); expect(deps.readArtistDocuments).toHaveBeenCalledWith(owner, [artist]); expect(deps.authorize).toHaveBeenCalledTimes(2); + expect(result.result.content).toMatchObject({ artistBrand: "not_established" }); + expect(deps.authorize).toHaveBeenNthCalledWith(1, owner, owner); + expect(deps.authorize).toHaveBeenNthCalledWith(2, owner, owner); + expect(deps.authorize.mock.invocationCallOrder[0]).toBeLessThan( + deps.readRequest.mock.invocationCallOrder[0], + ); + expect(deps.readRequest.mock.invocationCallOrder[0]).toBeLessThan( + deps.readEvidence.mock.invocationCallOrder[0], + ); + expect(deps.readEvidence.mock.invocationCallOrder[0]).toBeLessThan( + deps.readArtistDocuments.mock.invocationCallOrder[0], + ); + expect(deps.readArtistDocuments.mock.invocationCallOrder[0]).toBeLessThan( + deps.authorize.mock.invocationCallOrder[1], + ); expect(JSON.stringify(result.module)).not.toContain('"topic":"artist_brand"'); }); it.each(["live", "remix", "dubbed", "unknown"])( @@ -204,6 +219,7 @@ it("stops before evidence reads on denied access and rechecks before returning", const { deps } = fixture(); deps.authorize.mockRejectedValueOnce(new Error("Denied")); await expect(prepare(deps)).rejects.toThrow("Denied"); + expect(deps.readRequest).not.toHaveBeenCalled(); expect(deps.readEvidence).not.toHaveBeenCalled(); deps.authorize.mockResolvedValueOnce(true).mockRejectedValueOnce(new Error("Revoked")); await expect(prepare(deps)).rejects.toThrow("Revoked"); @@ -325,3 +341,42 @@ it("excludes source withdrawal case aliases", async () => { }); expect((await prepare(deps)).reusedArtistDocuments).toEqual([]); }); + +it("canonicalizes request/owner/actor and credited artist UUIDs before reader calls", async () => { + const { evidence, deps } = fixture(); + const account = "abcdefab-abcd-4abc-8abc-abcdefabcdef"; + const request = "bcdefabc-bcde-4bcd-8bcd-bcdefabcdefa"; + const credited = "cdefabcd-cdef-4cde-8cde-cdefabcdefab"; + evidence.ownerId = account.toUpperCase(); + evidence.requestId = request.toUpperCase(); + evidence.identity.creditedArtists[0].subjectId = credited.toUpperCase(); + deps.readRequest.mockResolvedValue({ + id: request, + owner_id: account, + created_by: account, + input: { url }, + status: "partial", + }); + await prepareContextVideoEvidence( + account.toUpperCase(), + account.toUpperCase(), + request.toUpperCase(), + deps, + ); + expect(deps.authorize).toHaveBeenNthCalledWith(1, account, account); + expect(deps.authorize).toHaveBeenNthCalledWith(2, account, account); + expect(deps.readRequest).toHaveBeenCalledWith(account, request); + expect(deps.readEvidence).toHaveBeenCalledWith(account, request); + expect(deps.readArtistDocuments).toHaveBeenCalledWith(account, [credited]); +}); +it.each(["\u0000", "\u0001", "\ud800", "\udfff"])( + "rejects malformed retained text %j without sanitizing it", + async invalid => { + for (const field of ["title", "description", "language"]) { + const { evidence, deps } = fixture(); + if (field === "language") evidence.captions.segments[0].language = "en" + invalid; + else Object.assign(evidence, { [field]: "retained" + invalid }); + await expect(prepare(deps)).rejects.toThrow(); + } + }, +); diff --git a/lib/context/video/contextVideoEvidenceSchema.ts b/lib/context/video/contextVideoEvidenceSchema.ts index 767659130..6b4b79b6e 100644 --- a/lib/context/video/contextVideoEvidenceSchema.ts +++ b/lib/context/video/contextVideoEvidenceSchema.ts @@ -1,7 +1,12 @@ import { z } from "zod"; -const text = z +const retainedText = z .string() + .refine( + value => !/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f\p{Cs}]/u.test(value), + "Malformed retained text", + ); +const text = retainedText .min(1) .max(4000) .refine(value => /[^\s\p{Cf}\p{Default_Ignorable_Code_Point}]/u.test(value)); @@ -27,7 +32,7 @@ export const contextVideoEvidenceSchema = z durationSeconds: z.number().positive().finite().nullable(), variant: z.enum(["original", "live", "remix", "dubbed", "unknown"]), title: text, - description: z.string().max(20000), + description: retainedText.max(20000), channel: z.strictObject({ id: text, name: text }), performers: z.array(z.strictObject({ name: text, sourceVersionIds: references })).max(50), identity: z.discriminatedUnion("state", [ @@ -59,7 +64,7 @@ export const contextVideoEvidenceSchema = z state: z.literal("available"), sourceVersionIds: references, segments: z - .array(z.strictObject({ ...range, language: z.string().min(1).max(100), text })) + .array(z.strictObject({ ...range, language: retainedText.min(1).max(100), text })) .min(1) .max(500), }), diff --git a/lib/context/video/prepareContextVideoEvidence.ts b/lib/context/video/prepareContextVideoEvidence.ts index 093eae273..48902c9e1 100644 --- a/lib/context/video/prepareContextVideoEvidence.ts +++ b/lib/context/video/prepareContextVideoEvidence.ts @@ -1,6 +1,7 @@ import { z } from "zod"; import { parseContextUrl } from "../parseContextUrl"; -import { selectContextDocuments, type ContextBriefDocument } from "../selectContextDocuments"; +import type { ContextBriefDocument } from "../selectContextDocuments"; +import { selectContextVideoArtistResearch } from "./selectContextVideoArtistResearch"; import type { ContextRequestRecord } from "../runContextRequest"; import type { ContextEnrichmentModule, @@ -33,14 +34,15 @@ export async function prepareContextVideoEvidence( result: ContextEnrichmentResult; reusedArtistDocuments: ContextBriefDocument[]; }> { - z.uuid().parse(owner); - z.uuid().parse(requestId); + actor = z.uuid().parse(actor).toLowerCase(); + owner = z.uuid().parse(owner).toLowerCase(); + requestId = z.uuid().parse(requestId).toLowerCase(); await deps.authorize(actor, owner); const request = await deps.readRequest(owner, requestId); if ( !request || - request.id !== requestId || - request.owner_id !== owner || + request.id.toLowerCase() !== requestId || + request.owner_id.toLowerCase() !== owner || request.status === "cancelled" ) throw new Error("Video context request unavailable"); @@ -48,38 +50,18 @@ export async function prepareContextVideoEvidence( if (resource.provider !== "youtube") throw new Error("Single YouTube video required"); const evidence = contextVideoEvidenceSchema.parse(await deps.readEvidence(owner, requestId)); if ( - evidence.requestId !== requestId || - evidence.ownerId !== owner || + evidence.requestId.toLowerCase() !== requestId || + evidence.ownerId.toLowerCase() !== owner || evidence.videoId !== resource.id ) throw new Error("Video evidence does not match the selected request"); let reusedArtistDocuments: ContextBriefDocument[] = []; if (evidence.identity.state === "matched") { - const subjectIds = evidence.identity.creditedArtists.map(artist => artist.subjectId); + const subjectIds = evidence.identity.creditedArtists.map(artist => + artist.subjectId.toLowerCase(), + ); const saved = await deps.readArtistDocuments(owner, subjectIds); - if (saved.documents.length > 1000 || saved.withdrawnSourceVersionIds.length > 32000) - throw new Error("Artist evidence exceeds bounded selection"); - // Compare UUID identity canonically; return retained documents byte-for-byte unchanged. - const originals = new Map(); - for (const document of saved.documents.filter(doc => Boolean(doc.resultId))) { - originals.set( - { - ...document, - ownerId: document.ownerId.toLowerCase(), - subjectId: document.subjectId.toLowerCase(), - sourceVersionIds: document.sourceVersionIds.map(id => id.toLowerCase()), - }, - document, - ); - } - reusedArtistDocuments = selectContextDocuments([...originals.keys()], { - ownerId: owner.toLowerCase(), - subjectIds: subjectIds.map(id => id.toLowerCase()), - topics: ["artist_research"], - maxCharacters: 32000, - requiredCoverage: "partial", - withdrawnSourceVersionIds: saved.withdrawnSourceVersionIds.map(id => id.toLowerCase()), - }).documents.map(document => originals.get(document)!); + reusedArtistDocuments = selectContextVideoArtistResearch(owner, subjectIds, saved); } await deps.authorize(actor, owner); const sources = evidence.sources.map(source => ({ diff --git a/lib/context/video/selectContextVideoArtistResearch.ts b/lib/context/video/selectContextVideoArtistResearch.ts new file mode 100644 index 000000000..2277a5a15 --- /dev/null +++ b/lib/context/video/selectContextVideoArtistResearch.ts @@ -0,0 +1,31 @@ +import { selectContextDocuments, type ContextBriefDocument } from "../selectContextDocuments"; + +/** Compare UUIDs canonically while returning the original authorized document objects. */ +export function selectContextVideoArtistResearch( + owner: string, + subjectIds: string[], + saved: { documents: ContextBriefDocument[]; withdrawnSourceVersionIds: string[] }, +): ContextBriefDocument[] { + if (saved.documents.length > 1000 || saved.withdrawnSourceVersionIds.length > 32000) + throw new Error("Artist evidence exceeds bounded selection"); + const originals = new Map(); + for (const document of saved.documents.filter(doc => Boolean(doc.resultId))) { + originals.set( + { + ...document, + ownerId: document.ownerId.toLowerCase(), + subjectId: document.subjectId.toLowerCase(), + sourceVersionIds: document.sourceVersionIds.map(id => id.toLowerCase()), + }, + document, + ); + } + return selectContextDocuments([...originals.keys()], { + ownerId: owner.toLowerCase(), + subjectIds: subjectIds.map(id => id.toLowerCase()), + topics: ["artist_research"], + maxCharacters: 32000, + requiredCoverage: "partial", + withdrawnSourceVersionIds: saved.withdrawnSourceVersionIds.map(id => id.toLowerCase()), + }).documents.map(document => originals.get(document)!); +} From 0aa8605a6a898fa20e338cc613460423c3d596ba Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Wed, 18 Nov 2026 07:32:08 -0500 Subject: [PATCH 5/5] Separate retained video loading and projection responsibilities --- lib/context/video/README.md | 13 + .../prepareContextVideoEvidence.test.ts | 53 ++++ .../video/contextVideoEvidenceSchema.ts | 244 ++++++++++-------- lib/context/video/contextVideoLimits.ts | 14 + lib/context/video/loadContextVideoEvidence.ts | 35 +++ .../video/prepareContextVideoEvidence.ts | 76 +----- .../video/projectContextVideoEvidence.ts | 44 ++++ .../video/selectContextVideoArtistResearch.ts | 8 +- 8 files changed, 308 insertions(+), 179 deletions(-) create mode 100644 lib/context/video/contextVideoLimits.ts create mode 100644 lib/context/video/loadContextVideoEvidence.ts create mode 100644 lib/context/video/projectContextVideoEvidence.ts diff --git a/lib/context/video/README.md b/lib/context/video/README.md index 6c6d50bae..27755c0f6 100644 --- a/lib/context/video/README.md +++ b/lib/context/video/README.md @@ -61,3 +61,16 @@ versions, unresolved identity, multiple languages, partial ranges, unavailable media, source/version and owner/request mismatch, revoked access and filtered reuse. These demonstrate source behavior only; they do not establish collection, Database acceptance, live accounting, ingestion or hosted availability. + +## Internal responsibilities + +The preparation function owns canonical scope arguments and authorization/read +ordering. `loadContextVideoEvidence` loads and validates request/evidence binding +only after that first authorization. `selectContextVideoArtistResearch` performs +bounded reuse; its Map pairs each comparison-only copy with its original object, +so duplicate document identifiers cannot make restoration ambiguous. +`projectContextVideoEvidence` is a pure constructor over validated evidence; it +returns the unchanged shared module/result contract after final authorization. +Named limits keep text budgets distinct from counts. Source binding, analyzed +range and identity separation are named validators beside their one schema. +None of these internal helpers grants access or supplies a production reader. diff --git a/lib/context/video/__tests__/prepareContextVideoEvidence.test.ts b/lib/context/video/__tests__/prepareContextVideoEvidence.test.ts index 62c7b7ced..bf080427d 100644 --- a/lib/context/video/__tests__/prepareContextVideoEvidence.test.ts +++ b/lib/context/video/__tests__/prepareContextVideoEvidence.test.ts @@ -380,3 +380,56 @@ it.each(["\u0000", "\u0001", "\ud800", "\udfff"])( } }, ); + +it("preserves the complete shared projection and exact original research object after extraction", async () => { + const { evidence, deps } = fixture(); + const original = { ...document }; + deps.readArtistDocuments.mockResolvedValue({ + documents: [original], + withdrawnSourceVersionIds: [], + }); + const prepared = await prepare(deps); + expect(prepared.module).toEqual({ + key: "video-narrative-fixture-v1", + topic: "video_narrative", + subjectId: videoSubject, + provider: "retained-evidence", + model: "none", + evidenceKind: "interpretation", + input: evidence, + sources: [{ url, kind: "provider_metadata", content: evidence.sources[0] }], + }); + expect(prepared.result).toEqual({ + content: { + ...evidence, + originalSongLyrics: "not_established", + scope: "video_only", + artistBrand: "not_established", + }, + coverage: "partial", + costUsd: null, + costStatus: "unknown", + trace: { method: "retained_video_projection", sourceVersionIds: [sourceId] }, + }); + expect(prepared.reusedArtistDocuments[0]).toBe(original); +}); +it("keeps participant, language and retained-text limits unchanged", async () => { + for (const mutate of [ + (evidence: ReturnType["evidence"]) => { + evidence.title = "x".repeat(4001); + }, + (evidence: ReturnType["evidence"]) => { + evidence.description = "x".repeat(20001); + }, + (evidence: ReturnType["evidence"]) => { + evidence.captions.segments[0].language = "x".repeat(101); + }, + (evidence: ReturnType["evidence"]) => { + evidence.performers = Array.from({ length: 51 }, () => evidence.performers[0]); + }, + ]) { + const { evidence, deps } = fixture(); + mutate(evidence); + await expect(prepare(deps)).rejects.toThrow(); + } +}); diff --git a/lib/context/video/contextVideoEvidenceSchema.ts b/lib/context/video/contextVideoEvidenceSchema.ts index 6b4b79b6e..720d2cb29 100644 --- a/lib/context/video/contextVideoEvidenceSchema.ts +++ b/lib/context/video/contextVideoEvidenceSchema.ts @@ -1,4 +1,5 @@ import { z } from "zod"; +import { contextVideoLimits as limits } from "./contextVideoLimits"; const retainedText = z .string() @@ -8,12 +9,12 @@ const retainedText = z ); const text = retainedText .min(1) - .max(4000) + .max(limits.textCharacters) .refine(value => /[^\s\p{Cf}\p{Default_Ignorable_Code_Point}]/u.test(value)); const references = z .array(z.uuid()) .min(1) - .max(32) + .max(limits.sourceVersions) .refine(ids => new Set(ids.map(id => id.toLowerCase())).size === ids.length); const range = { startSeconds: z.number().nonnegative().finite(), @@ -22,117 +23,138 @@ const range = { const unavailable = z.strictObject({ state: z.enum(["missing", "unavailable"]), reason: text }); /** Retained, authorized evidence supplied by an injected reader; never a public identity assertion. */ -export const contextVideoEvidenceSchema = z - .strictObject({ - requestId: z.uuid(), - ownerId: z.uuid(), - videoSubjectId: z.uuid(), - videoId: z.string().regex(/^[A-Za-z0-9_-]{11}$/), - mediaVersion: text, - durationSeconds: z.number().positive().finite().nullable(), - variant: z.enum(["original", "live", "remix", "dubbed", "unknown"]), - title: text, - description: retainedText.max(20000), - channel: z.strictObject({ id: text, name: text }), - performers: z.array(z.strictObject({ name: text, sourceVersionIds: references })).max(50), - identity: z.discriminatedUnion("state", [ - z.strictObject({ state: z.literal("unresolved"), reason: text }), +const evidenceShape = z.strictObject({ + requestId: z.uuid(), + ownerId: z.uuid(), + videoSubjectId: z.uuid(), + videoId: z.string().regex(/^[A-Za-z0-9_-]{11}$/), + mediaVersion: text, + durationSeconds: z.number().positive().finite().nullable(), + variant: z.enum(["original", "live", "remix", "dubbed", "unknown"]), + title: text, + description: retainedText.max(limits.descriptionCharacters), + channel: z.strictObject({ id: text, name: text }), + performers: z + .array(z.strictObject({ name: text, sourceVersionIds: references })) + .max(limits.participants), + identity: z.discriminatedUnion("state", [ + z.strictObject({ state: z.literal("unresolved"), reason: text }), + z.strictObject({ + state: z.literal("matched"), + recordingSubjectId: z.uuid(), + creditedArtists: z + .array(z.strictObject({ subjectId: z.uuid(), name: text })) + .min(1) + .max(limits.participants), + sourceVersionIds: references, + }), + ]), + sources: z + .array( z.strictObject({ - state: z.literal("matched"), - recordingSubjectId: z.uuid(), - creditedArtists: z - .array(z.strictObject({ subjectId: z.uuid(), name: text })) - .min(1) - .max(50), - sourceVersionIds: references, + versionId: z.uuid(), + videoId: z.string(), + mediaVersion: text, + retrievedAt: z.iso.datetime(), }), - ]), - sources: z - .array( - z.strictObject({ - versionId: z.uuid(), - videoId: z.string(), - mediaVersion: text, - retrievedAt: z.iso.datetime(), - }), - ) - .min(1) - .max(32), - captions: z.union([ - unavailable, - z.strictObject({ - state: z.literal("available"), - sourceVersionIds: references, - segments: z - .array(z.strictObject({ ...range, language: retainedText.min(1).max(100), text })) - .min(1) - .max(500), - }), - ]), - analysis: z.union([ - unavailable, - z.strictObject({ - state: z.literal("available"), - sourceVersionIds: references, - ranges: z - .array( - z.strictObject({ - ...range, - observations: z.array(text).min(1).max(50), - interpretation: text, - }), - ) - .min(1) - .max(100), - }), - ]), - }) - .superRefine((evidence, ctx) => { - const ids = new Set(evidence.sources.map(source => source.versionId.toLowerCase())); - const references = [ - ...evidence.performers.flatMap(person => person.sourceVersionIds), - ...(evidence.identity.state === "matched" ? evidence.identity.sourceVersionIds : []), - ...(evidence.captions.state === "available" ? evidence.captions.sourceVersionIds : []), - ...(evidence.analysis.state === "available" ? evidence.analysis.sourceVersionIds : []), - ]; - const ranges = [ - ...(evidence.captions.state === "available" ? evidence.captions.segments : []), - ...(evidence.analysis.state === "available" ? evidence.analysis.ranges : []), - ]; - if ( - ids.size !== evidence.sources.length || - references.some(id => !ids.has(id.toLowerCase())) || - evidence.sources.some( - source => - source.videoId !== evidence.videoId || source.mediaVersion !== evidence.mediaVersion, - ) ) - ctx.addIssue({ - code: "custom", - message: "Video evidence requires exact retained source/version bindings", - }); - if ( - ranges.some( - range => - range.endSeconds <= range.startSeconds || - (evidence.durationSeconds !== null && range.endSeconds > evidence.durationSeconds), - ) + .min(1) + .max(limits.sourceVersions), + captions: z.union([ + unavailable, + z.strictObject({ + state: z.literal("available"), + sourceVersionIds: references, + segments: z + .array( + z.strictObject({ + ...range, + language: retainedText.min(1).max(limits.languageCharacters), + text, + }), + ) + .min(1) + .max(limits.captionSegments), + }), + ]), + analysis: z.union([ + unavailable, + z.strictObject({ + state: z.literal("available"), + sourceVersionIds: references, + ranges: z + .array( + z.strictObject({ + ...range, + observations: z.array(text).min(1).max(limits.observationsPerRange), + interpretation: text, + }), + ) + .min(1) + .max(limits.analysisRanges), + }), + ]), +}); + +export type ContextVideoEvidence = z.infer; + +function validateSourceBindings(evidence: ContextVideoEvidence, ctx: z.RefinementCtx) { + const ids = new Set(evidence.sources.map(source => source.versionId.toLowerCase())); + const references = [ + ...evidence.performers.flatMap(person => person.sourceVersionIds), + ...(evidence.identity.state === "matched" ? evidence.identity.sourceVersionIds : []), + ...(evidence.captions.state === "available" ? evidence.captions.sourceVersionIds : []), + ...(evidence.analysis.state === "available" ? evidence.analysis.sourceVersionIds : []), + ]; + if ( + ids.size !== evidence.sources.length || + references.some(id => !ids.has(id.toLowerCase())) || + evidence.sources.some( + source => + source.videoId !== evidence.videoId || source.mediaVersion !== evidence.mediaVersion, ) - ctx.addIssue({ code: "custom", message: "Invalid analyzed video range" }); - const identity = evidence.identity; - if ( - identity.state === "matched" && - (identity.recordingSubjectId.toLowerCase() === evidence.videoSubjectId.toLowerCase() || - identity.creditedArtists.some( - artist => - artist.subjectId.toLowerCase() === evidence.videoSubjectId.toLowerCase() || - artist.subjectId.toLowerCase() === identity.recordingSubjectId.toLowerCase(), - ) || - new Set(identity.creditedArtists.map(artist => artist.subjectId.toLowerCase())).size !== - identity.creditedArtists.length) + ) + ctx.addIssue({ + code: "custom", + message: "Video evidence requires exact retained source/version bindings", + }); +} + +function validateAnalyzedRanges(evidence: ContextVideoEvidence, ctx: z.RefinementCtx) { + const ranges = [ + ...(evidence.captions.state === "available" ? evidence.captions.segments : []), + ...(evidence.analysis.state === "available" ? evidence.analysis.ranges : []), + ]; + if ( + ranges.some( + range => + range.endSeconds <= range.startSeconds || + (evidence.durationSeconds !== null && range.endSeconds > evidence.durationSeconds), ) - ctx.addIssue({ - code: "custom", - message: "Video, recording and credited artist identities must remain separate", - }); - }); + ) + ctx.addIssue({ code: "custom", message: "Invalid analyzed video range" }); +} + +function validateIdentitySeparation(evidence: ContextVideoEvidence, ctx: z.RefinementCtx) { + const identity = evidence.identity; + if ( + identity.state === "matched" && + (identity.recordingSubjectId.toLowerCase() === evidence.videoSubjectId.toLowerCase() || + identity.creditedArtists.some( + artist => + artist.subjectId.toLowerCase() === evidence.videoSubjectId.toLowerCase() || + artist.subjectId.toLowerCase() === identity.recordingSubjectId.toLowerCase(), + ) || + new Set(identity.creditedArtists.map(artist => artist.subjectId.toLowerCase())).size !== + identity.creditedArtists.length) + ) + ctx.addIssue({ + code: "custom", + message: "Video, recording and credited artist identities must remain separate", + }); +} + +export const contextVideoEvidenceSchema = evidenceShape + .superRefine(validateSourceBindings) + .superRefine(validateAnalyzedRanges) + .superRefine(validateIdentitySeparation); diff --git a/lib/context/video/contextVideoLimits.ts b/lib/context/video/contextVideoLimits.ts new file mode 100644 index 000000000..210fef9c8 --- /dev/null +++ b/lib/context/video/contextVideoLimits.ts @@ -0,0 +1,14 @@ +/** Bounds for this retained-evidence fixture contract; counts and text budgets are distinct. */ +export const contextVideoLimits = Object.freeze({ + textCharacters: 4000, + descriptionCharacters: 20000, + sourceVersions: 32, + participants: 50, + languageCharacters: 100, + captionSegments: 500, + analysisRanges: 100, + observationsPerRange: 50, + artistDocuments: 1000, + withdrawnSourceVersions: 32000, + artistResearchCharacters: 32000, +}); diff --git a/lib/context/video/loadContextVideoEvidence.ts b/lib/context/video/loadContextVideoEvidence.ts new file mode 100644 index 000000000..a4ad289bf --- /dev/null +++ b/lib/context/video/loadContextVideoEvidence.ts @@ -0,0 +1,35 @@ +import type { ContextRequestRecord } from "../runContextRequest"; +import { parseContextUrl } from "../parseContextUrl"; +import { contextVideoEvidenceSchema } from "./contextVideoEvidenceSchema"; + +export type ContextVideoEvidenceReaders = { + readRequest: (owner: string, requestId: string) => Promise; + /** Return retained authorized evidence; never infer identity from the uploader. */ + readEvidence: (owner: string, requestId: string) => Promise; +}; + +/** Load and bind one retained request after caller authorization, using canonical scope UUIDs. */ +export async function loadContextVideoEvidence( + owner: string, + requestId: string, + deps: ContextVideoEvidenceReaders, +) { + const request = await deps.readRequest(owner, requestId); + if ( + !request || + request.id.toLowerCase() !== requestId || + request.owner_id.toLowerCase() !== owner || + request.status === "cancelled" + ) + throw new Error("Video context request unavailable"); + const resource = parseContextUrl(request.input.url); + if (resource.provider !== "youtube") throw new Error("Single YouTube video required"); + const evidence = contextVideoEvidenceSchema.parse(await deps.readEvidence(owner, requestId)); + if ( + evidence.requestId.toLowerCase() !== requestId || + evidence.ownerId.toLowerCase() !== owner || + evidence.videoId !== resource.id + ) + throw new Error("Video evidence does not match the selected request"); + return { resourceUrl: resource.url, evidence }; +} diff --git a/lib/context/video/prepareContextVideoEvidence.ts b/lib/context/video/prepareContextVideoEvidence.ts index 48902c9e1..b3a04ca17 100644 --- a/lib/context/video/prepareContextVideoEvidence.ts +++ b/lib/context/video/prepareContextVideoEvidence.ts @@ -1,19 +1,14 @@ import { z } from "zod"; -import { parseContextUrl } from "../parseContextUrl"; import type { ContextBriefDocument } from "../selectContextDocuments"; import { selectContextVideoArtistResearch } from "./selectContextVideoArtistResearch"; -import type { ContextRequestRecord } from "../runContextRequest"; -import type { - ContextEnrichmentModule, - ContextEnrichmentResult, -} from "../enrichment/runContextEnrichment"; -import { contextVideoEvidenceSchema } from "./contextVideoEvidenceSchema"; +import { + loadContextVideoEvidence, + type ContextVideoEvidenceReaders, +} from "./loadContextVideoEvidence"; +import { projectContextVideoEvidence } from "./projectContextVideoEvidence"; -type Dependencies = { +type Dependencies = ContextVideoEvidenceReaders & { authorize: (actor: string, owner: string) => Promise; - readRequest: (owner: string, requestId: string) => Promise; - /** Must return retained evidence from authorized sources, never infer identity from the uploader. */ - readEvidence: (owner: string, requestId: string) => Promise; readArtistDocuments: ( owner: string, artistSubjectIds: string[], @@ -23,38 +18,18 @@ type Dependencies = { }>; }; -/** Prepare one fixture-only video projection. No collection, persistence, accounting or public dispatch. */ +/** Authorize, load retained evidence, reuse saved research, then reauthorize before projection. */ export async function prepareContextVideoEvidence( actor: string, owner: string, requestId: string, deps: Dependencies, -): Promise<{ - module: ContextEnrichmentModule; - result: ContextEnrichmentResult; - reusedArtistDocuments: ContextBriefDocument[]; -}> { +) { actor = z.uuid().parse(actor).toLowerCase(); owner = z.uuid().parse(owner).toLowerCase(); requestId = z.uuid().parse(requestId).toLowerCase(); await deps.authorize(actor, owner); - const request = await deps.readRequest(owner, requestId); - if ( - !request || - request.id.toLowerCase() !== requestId || - request.owner_id.toLowerCase() !== owner || - request.status === "cancelled" - ) - throw new Error("Video context request unavailable"); - const resource = parseContextUrl(request.input.url); - if (resource.provider !== "youtube") throw new Error("Single YouTube video required"); - const evidence = contextVideoEvidenceSchema.parse(await deps.readEvidence(owner, requestId)); - if ( - evidence.requestId.toLowerCase() !== requestId || - evidence.ownerId.toLowerCase() !== owner || - evidence.videoId !== resource.id - ) - throw new Error("Video evidence does not match the selected request"); + const { resourceUrl, evidence } = await loadContextVideoEvidence(owner, requestId, deps); let reusedArtistDocuments: ContextBriefDocument[] = []; if (evidence.identity.state === "matched") { const subjectIds = evidence.identity.creditedArtists.map(artist => @@ -64,36 +39,5 @@ export async function prepareContextVideoEvidence( reusedArtistDocuments = selectContextVideoArtistResearch(owner, subjectIds, saved); } await deps.authorize(actor, owner); - const sources = evidence.sources.map(source => ({ - url: resource.url, - kind: "provider_metadata", - content: source, - })); - const module: ContextEnrichmentModule = { - key: "video-narrative-fixture-v1", - topic: "video_narrative", - subjectId: evidence.videoSubjectId, - provider: "retained-evidence", - model: "none", - evidenceKind: "interpretation", - input: evidence, - sources, - }; - const result: ContextEnrichmentResult = { - content: { - ...evidence, - originalSongLyrics: "not_established", - scope: "video_only", - artistBrand: "not_established", - }, - // No projection can establish original-song completeness, even with every video frame analyzed. - coverage: "partial", - costUsd: null, - costStatus: "unknown", - trace: { - method: "retained_video_projection", - sourceVersionIds: evidence.sources.map(source => source.versionId), - }, - }; - return { module, result, reusedArtistDocuments }; + return { ...projectContextVideoEvidence(resourceUrl, evidence), reusedArtistDocuments }; } diff --git a/lib/context/video/projectContextVideoEvidence.ts b/lib/context/video/projectContextVideoEvidence.ts new file mode 100644 index 000000000..696958391 --- /dev/null +++ b/lib/context/video/projectContextVideoEvidence.ts @@ -0,0 +1,44 @@ +import type { ContextVideoEvidence } from "./contextVideoEvidenceSchema"; +import type { + ContextEnrichmentModule, + ContextEnrichmentResult, +} from "../enrichment/runContextEnrichment"; + +/** Pure video-only projection; no reader calls, authorization decision or persistence. */ +export function projectContextVideoEvidence( + resourceUrl: string, + evidence: ContextVideoEvidence, +): { module: ContextEnrichmentModule; result: ContextEnrichmentResult } { + const sources = evidence.sources.map(source => ({ + url: resourceUrl, + kind: "provider_metadata", + content: source, + })); + const module: ContextEnrichmentModule = { + key: "video-narrative-fixture-v1", + topic: "video_narrative", + subjectId: evidence.videoSubjectId, + provider: "retained-evidence", + model: "none", + evidenceKind: "interpretation", + input: evidence, + sources, + }; + const result: ContextEnrichmentResult = { + content: { + ...evidence, + originalSongLyrics: "not_established", + scope: "video_only", + artistBrand: "not_established", + }, + // No projection can establish original-song completeness, even with every video frame analyzed. + coverage: "partial", + costUsd: null, + costStatus: "unknown", + trace: { + method: "retained_video_projection", + sourceVersionIds: evidence.sources.map(source => source.versionId), + }, + }; + return { module, result }; +} diff --git a/lib/context/video/selectContextVideoArtistResearch.ts b/lib/context/video/selectContextVideoArtistResearch.ts index 2277a5a15..e66a56a79 100644 --- a/lib/context/video/selectContextVideoArtistResearch.ts +++ b/lib/context/video/selectContextVideoArtistResearch.ts @@ -1,3 +1,4 @@ +import { contextVideoLimits as limits } from "./contextVideoLimits"; import { selectContextDocuments, type ContextBriefDocument } from "../selectContextDocuments"; /** Compare UUIDs canonically while returning the original authorized document objects. */ @@ -6,7 +7,10 @@ export function selectContextVideoArtistResearch( subjectIds: string[], saved: { documents: ContextBriefDocument[]; withdrawnSourceVersionIds: string[] }, ): ContextBriefDocument[] { - if (saved.documents.length > 1000 || saved.withdrawnSourceVersionIds.length > 32000) + if ( + saved.documents.length > limits.artistDocuments || + saved.withdrawnSourceVersionIds.length > limits.withdrawnSourceVersions + ) throw new Error("Artist evidence exceeds bounded selection"); const originals = new Map(); for (const document of saved.documents.filter(doc => Boolean(doc.resultId))) { @@ -24,7 +28,7 @@ export function selectContextVideoArtistResearch( ownerId: owner.toLowerCase(), subjectIds: subjectIds.map(id => id.toLowerCase()), topics: ["artist_research"], - maxCharacters: 32000, + maxCharacters: limits.artistResearchCharacters, requiredCoverage: "partial", withdrawnSourceVersionIds: saved.withdrawnSourceVersionIds.map(id => id.toLowerCase()), }).documents.map(document => originals.get(document)!);