◎ OS PUB Apache 2.0 ← All specifications

P127 — AIEP — Replayable Reasoning Chain Evidence Substrate

Publication Date: 2026-03-01 Status: Open Source Prior Art Disclosure Licence: Apache License 2.0 Author/Organisation: Phatfella Ltd Schema: AIEP_OS_SPEC_TEMPLATE v1.0.1 — https://aiep.dev/schemas/aiep-os-spec-template/v1.0.1

Framework Context

[0001] This disclosure operates within an Architected Instruction and Evidence Protocol (AIEP) environment as defined in United Kingdom patent application number GB2519711.2, filed 20 November 2025, and GB2519798.9, filed 20 November 2025, the entire contents of which are incorporated herein by reference.

[0002] The present disclosure extends the Evidence Rail architecture defined in P37 and the genome-kernel commitment chain defined in P87 to the specific application of per-query reasoning chain capture, serialisation, and client-side replay.

Field of the Disclosure

[0003] This disclosure relates to governed artificial intelligence reasoning substrates that produce auditable, replayable records of multi-step inference processes.

[0004] More particularly, the disclosure concerns a mechanism within a PIEA Evidence Rail substrate for capturing each distinct reasoning phase as a timestamped, labelled, evidence-bound step record — the ReasoningStep — and streaming those records to a client over the same server-sent event (SSE) channel that delivers the primary inference response, such that the client may replay the full reasoning process in correct temporal sequence.

Background

[0005] Governed AI systems produce responses that must be auditable. Audability in existing systems typically means: retaining the prompt, the response, and optionally citations. The intermediate reasoning phases — query classification, source retrieval, inference model selection, confidence qualification, and response commitment — are not individually captured, timestamped, or surfaced to the client.

[0006] Without per-step records, an audit of an AI response cannot answer: (a) which query class drove source selection; (b) how many sources were retrieved and what retrieval timestamp was associated with each; (c) which inference model was actually invoked; (d) what confidence tier was assigned and on what basis; or (e) what the cryptographic commitment hash of the final response was, relative to what timestamp.

[0007] Existing structured log systems capture events but do not: (a) bind each step to the evidence artefacts active at that step; (b) stream per-step records to the client in real time; (c) associate each step with a nanosecond-resolution ISO 8601 timestamp enabling replay in wall-clock sequence; or (d) include a terminal step whose detail field contains the leading characters of the genome-committed response hash, enabling the replay to terminate at a verifiable cryptographic anchor.

Summary of the Disclosure

[0008] A ReasoningStep record comprises: a sequential ordinal (step); a human-readable label (label); a machine-readable detail string (detail) including quantitative evidence of process state (source count, model identifier, confidence tier, hash prefix); an ISO 8601 timestamp (ts) recorded immediately after the step operation completes; and optional context fields (artefact_count, model, query_class) populated when the step produces those values.

[0009] The following five canonical steps are defined for queries routed through the full Evidence Rail path:

Step	Label	Captures
1	Query Classification	`query_class` value from classifier
2	Source Discovery	artefact count after retrieval and deduplication
3	Evidence Reasoning	`model` identifier used for inference
4	Confidence Assessment	tier string and source count
5	Response Committed	leading 20 characters of genome-committed response hash

[0010] Conversational fast-path responses (queries classified as conversational) return an empty reasoning_steps array, indicating that the Evidence Rail was not invoked for that turn. This preserves the contract that reasoning_steps.length === 0 unambiguously identifies non-sourced responses.

[0011] The serialised steps array is streamed to the client as a steps server-sent event immediately before the done event on the same SSE channel. This ordering guarantees that: (a) all token events have been sent before steps are streamed; (b) the client receives a complete reasoning_steps array atomically before the stream closes; and (c) the done event remains the final signal that marks inference completion.

[0012] The steps event payload is { "steps": ReasoningStep[] }. The client accumulates steps into the active message record and preserves them in session storage alongside the evidence rail and response hash, enabling reconstruction of the full reasoning trace from a stored session.

[0013] The retrieved_at field on each EvidenceRef artefact records the ISO 8601 timestamp at which that artefact’s source URL was fetched and its content hashed. This timestamp appears in Step 2’s detail alongside artefact count, and is surfaced in the Evidence Rail UI to enable per-source temporal auditing.

[0014] The UI renders a collapsible Reasoning Replay panel below each completed piea response. The panel displays a numbered step chain with icon, label, detail, and wall-clock time for each step. A step-count badge is shown in the collapsed state to indicate the depth of the available trace.

Detailed Description

[0015] ReasoningStep Interface. The ReasoningStep interface is defined as:

interface ReasoningStep {
    step: number;       // 1-based ordinal within the chain
    label: string;      // human-readable step name
    detail: string;     // machine-readable process evidence
    ts: string;         // ISO 8601 timestamp, captured post-step
    artefact_count?: number;  // set at step 2 only
    model?: string;           // set at step 3 only
    query_class?: string;     // set at step 1 only
}

[0016] Capture Mechanism. Steps are captured inline within the ask() method of the PieaAgent class. A shared stepTs() closure captures new Date().toISOString() at the moment of each push. Steps are appended to a local steps: ReasoningStep[] array. The array is returned as the reasoning_steps property of the PieaResponse object. No separate logging path is required; the reasoning chain is a first-class field of the response.

[0017] Worker Integration. The Hono-based piea-worker inspects response.reasoning_steps after token streaming completes. If the array is non-empty, it emits send("steps", { steps: response.reasoning_steps }) before send("done", { response_id }). The steps are also persisted to the KV-backed session store as reasoning_steps on the stored message record, enabling retrieval from /api/sessions/:id.

[0018] Client Integration. The askStream() function in api.ts handles the steps SSE event and invokes callbacks.onSteps?.(data.steps). The Chat component stores steps on the Message object and passes them to <ReasoningReplay> for display.

[0019] Audit Properties. The combination of (a) genome-committed response hash, (b) per-step timestamps, (c) retrieval timestamps on each evidence artefact, and (d) the model identifier in Step 3 constitutes a cryptographically anchored, temporally ordered trace. The trace cannot be retroactively altered without invalidating the response hash.

Claims Narrative

[0020] The novel aspects of this disclosure are: (1) the capture of AI reasoning phases as first-class, timestamped, labelled step records returned as a top-level field of the inference response; (2) the streaming of the complete steps array as a server-sent event before the done event on the same SSE channel; (3) the persistence of the steps array in the session store alongside the response hash, enabling offline replay; (4) the terminal step whose detail field contains the leading characters of the genome-committed response hash, establishing a cryptographic anchor for the replay chain; and (5) the empty reasoning_steps array convention for conversational fast-path responses, enabling deterministic identification of non-evidence responses.

Brief Description of the Drawing

FIG. 1 — Reasoning Chain Capture and Streaming Architecture

   PieaAgent.ask()
   ┌──────────────────────────────────────────────────────────────┐
   │  step 1: classifyQuery()      → steps.push({step:1, ...})   │
   │  step 2: retrieveEvidence()   → steps.push({step:2, ...})   │
   │  step 3: runWorkersAI()       → steps.push({step:3, ...})   │
   │  step 4: qualifyResponse()    → steps.push({step:4, ...})   │
   │  step 5: response_commitment() → steps.push({step:5, ...})  │
   │                                                              │
   │  return PieaResponse { ..., reasoning_steps: steps }        │
   └──────────────────────────────────────────────────────────────┘
                │
                ▼
   piea-worker SSE path
   ┌──────────────────────────────────────────────────────────────┐
   │  for each word: send("token", {...})                         │
   │  if steps.length: send("steps", { steps })                  │
   │  send("done", { response_id })                              │
   └──────────────────────────────────────────────────────────────┘
                │
                ▼
   piea-ui Chat.tsx
   ┌──────────────────────────────────────────────────────────────┐
   │  onSteps: finalSteps = steps                                 │
   │  onDone: Message.reasoning_steps = finalSteps               │
   │  render: <ReasoningReplay steps={...} />                    │
   └──────────────────────────────────────────────────────────────┘