AI Narrative Adapter

Purpose

The AI narrative adapter converts a controlled package of canonical QLens research into a traceable publication draft. It MUST NOT create, revise, verify, or supersede canonical research objects.

Required boundary

1. QLens MUST resolve every source_oid before an AI request.
2. Only permitted research-object types from the publication's Research Space MAY enter the context package.
3. The provider MUST receive the publication contract, source records, statuses, versions, and a deterministic context digest.
4. Every generated section MUST cite one or more permitted source OIDs.
5. QLens MUST validate the structured response before writing a draft.
6. AI output MUST enter needs_review; it MUST NOT become public automatically.
7. API credentials MUST remain outside canonical YAML, generated files, browser JavaScript, and NUR pages.

Provider independence

NarrativeProvider is the stable interface. OpenAI is supplied as an optional adapter. A deterministic mock provider is available for tests and offline development.

Artifacts

Each AI revision produces:

• structured JSON;
• traceable Markdown;
• the exact source-context JSON;
• an immutable PublicationAIDraftGenerated event.

Failure conditions

Generation fails when a source is missing, outside the Research Space, of an unsupported type, or when the response contains an unknown OID, an untraceable section, or language that incorrectly upgrades provisional research.