notarius/docs/roadmap/3-portable-audita-infrastructure.md

Checkpoint 3: Portable Audita Infrastructure

Status

This document describes planned work, not implemented behavior.

Goal

Port or adapt reusable Audita infrastructure that directly supports Notarius contracts while avoiding Audita's transcript-correction model.

This checkpoint should add reusable runtime plumbing, not real extraction behavior.

Scope

In scope:

• structured LLM client interface implementation;
• LLM scheduler;
• prompt registry pattern;
• response-schema registry pattern;
• diagnostics run directory pattern;
• minimal config structs and defaults for implemented runtime pieces.

Out of scope:

• correction proposals;
• replacement policies;
• transcript mutation;
• correction ledger terminology;
• Audita module or validator behavior;
• real D&D prompts or schemas unless needed as inert registry tests.

Proposed Stages

Stage 1: LLM Runtime

Port or adapt the OpenAI-compatible structured-output client and scheduler.

Keep the contract transport-neutral:

• framework code should depend on a StructuredLLMClient interface;
• provider-specific HTTP details should remain in the LLM runtime package;
• errors must redact configured secrets.

Stage 2: Response Schema Registry

Port or adapt the embedded JSON response-schema registry pattern.

The registry should track:

• schema key;
• schema ID;
• schema version;
• schema name;
• JSON schema content;
• schema hash.

Use placeholder or test schemas if real extractor schemas are not ready.

Stage 3: Prompt Registry

Port or adapt the embedded prompt registry pattern.

The registry should track:

• prompt ID;
• prompt version;
• prompt source;
• embedded path;
• prompt hash.

Do not add D&D prompt assets here unless the implementation naturally overlaps with checkpoint 5. Test prompts are acceptable for registry tests.

Stage 4: Diagnostics Run Directory

Port or adapt the diagnostics run directory pattern.

Initial diagnostics should cover:

• invocation metadata;
• redacted effective config;
• source document artifact;
• run report placeholder;
• error log on failure.

Avoid Audita-specific artifact names such as correction ledger.

Stage 5: Minimal Runtime Config

Add config structs and defaults only for infrastructure that now exists.

Initial config areas:

• input adapter key;
• extractor keys;
• primary LLM settings;
• validation LLM settings if needed;
• concurrency;
• work directory;
• diagnostics retention.

Config loading can remain minimal unless the implementation needs full file/env precedence at this checkpoint.

Done Criteria

• go test ./... passes.
• Audita runtime pieces are adapted to Notarius package names and contracts.
• No correction proposal, replacement policy, transcript mutation, or correction ledger code has been copied.
• Runtime tests cover secret redaction, schema registry lookup, prompt metadata, and scheduler behavior where applicable.

Review Questions

• Did we copy only reusable infrastructure?
• Do provider-specific types stay behind adapter/runtime boundaries?
• Are diagnostics names and report concepts extraction-oriented?
• Is config limited to implemented behavior?