A pricing result is easy to store.

An audit-ready pricing run is harder.

The difference is that a pricing result tells you what the number was. An audit-ready run tells you how that number came into existence.

That distinction matters. In quantitative finance, a number rarely stands alone. An NPV, PV01, cashflow report, curve value, or scenario output depends on market data, portfolio inputs, instrument definitions, model assumptions, convention sets, engine versions, solver settings, scenario definitions, and validation rules.

If those pieces are not preserved, the result may be useful for a moment, but difficult to explain later.

An audit-ready pricing run should answer a simple set of questions:

What was priced?
Against which market data?
Under which conventions?
With which engine version?
Using which scenario definition?
What warnings or exceptions occurred?
Who ran it?
When was it run?
Can the result be reproduced?

If the system cannot answer those questions, then the pricing run is not truly audit-ready.

A pricing result is not enough

Most analytics workflows naturally focus on outputs.

That is understandable. Users usually care about the NPV, the cashflows, the sensitivities, the scenario P&L, or the aggregated portfolio report. The output is what gets reviewed, exported, shared, and acted upon.

But the output is only the final layer.

A pricing run is a chain of decisions and transformations. It begins with user-supplied inputs. Those inputs are parsed, validated, normalized, mapped to internal schemas, combined with market data, associated with convention sets, passed to a pricing engine, transformed into outputs, and finally displayed or exported.

Each step can affect the result.

That means an audit-ready run cannot consist only of the final output table. It needs to preserve the full context of the calculation.

A report that says:

Trade 1027: NPV = 1,248,391.22

is not enough.

A better report can answer:

This NPV was produced from portfolio version X, market snapshot Y, convention set Z, engine build A, QuantLib version B, solver settings C, and scenario definition D. The run was triggered by user E at time T. The inputs passed validation, one non-fatal warning was recorded, and the output artifact is linked to the full provenance chain.

That is the difference between a number and a traceable result.

The run identity

Every audit-ready pricing run needs a stable identity.

That identity should not be a filename, a spreadsheet tab, or an informal timestamp in a folder. It should be a proper run identifier that links the inputs, configuration, execution metadata, outputs, logs, warnings, and exported artifacts.

The run ID is the anchor.

Without a stable run ID, teams often end up asking questions like:

Which file produced this result?
Was this the final version or the earlier one?
Did we rerun this after the correction?
Is this the result from the base case or the shifted scenario?

A run ID gives the organization a durable reference point. It allows users, support teams, developers, and auditors to talk about the same calculation without ambiguity.

A useful run identity should include or link to:

• the run ID,
• the workspace or project,
• the tenant or organization,
• the user or system actor that triggered the run,
• the run type,
• the run status,
• the creation time,
• the completion time,
• and links to input and output artifacts.

The run identity should not depend on mutable context. If a portfolio is later corrected or a market snapshot is replaced, the original run should still point to the exact inputs it used at the time.

The input references

The most important part of an audit-ready run is the input record.

The system should not merely store that “a portfolio was uploaded” or “a market snapshot was used.” It should store exact references to the validated inputs.

For a basic pricing run, that usually means:

• portfolio reference,
• market snapshot reference,
• curve input reference,
• fixing data reference,
• convention set reference,
• pricing configuration reference,
• scenario set reference, if applicable.

These references should point to immutable or versioned artifacts.

This matters because input files evolve. A user may upload a corrected portfolio. A market snapshot may be replaced. A convention set may receive a new version. A scenario recipe may be modified.

If the run only points to “latest portfolio” or “current conventions,” then it cannot be reliably reproduced. Reproduction requires the exact inputs, not the current inputs.

The same principle applies to derived inputs.

If the system builds curves from market quotes, the pricing run should preserve not only the final curve outputs but also the curve construction inputs and configuration. Otherwise, a later reviewer may see a curve but not understand how it was built.

Validation status and input quality

An audit-ready run should record whether the inputs were validated before pricing.

This is especially important for uploaded portfolios and market snapshots. Financial input files are not just data. They encode assumptions. They may contain missing fields, malformed dates, unsupported instruments, ambiguous currency mappings, missing fixings, duplicated trade identifiers, or inconsistent conventions.

A pricing engine should not be the first place where these problems are discovered.

The run record should therefore include:

• validation status,
• validation timestamp,
• schema version used for validation,
• semantic validation checks,
• rejected rows or trades,
• warnings,
• non-fatal assumptions,
• and links to structured validation reports.

There is an important difference between a failed validation, a warning, and an accepted assumption.

For example:

• A missing required maturity date should probably fail validation.
• A missing optional desk label may produce a warning.
• A convention fallback should be explicit and visible, not silently applied.

The audit trail should make these distinctions clear.

If an input problem was corrected, that correction should produce a new validated artifact and a new run. The previous run should remain intact. This avoids a common source of confusion: old reports silently changing because old inputs were overwritten.

Convention sets

Conventions are one of the most important parts of an audit-ready pricing run.

They are also one of the easiest things to hide accidentally.

A trade can be represented correctly at the structural level but still produce different results under different conventions. Day-count rules, calendars, business-day adjustments, settlement lags, compounding assumptions, roll rules, fixing calendars, and curve mappings all affect the final output.

An audit-ready run should therefore record the convention set explicitly.

It should not rely on internal defaults that are invisible to the user. It should not rely on whatever the current library default happens to be. It should not allow a result to be produced without knowing which convention version was applied.

The run should include:

• convention set name,
• convention set version,
• market or currency scope,
• effective date or validity range, if relevant,
• all overrides applied to the run,
• and the relationship between conventions and instrument definitions.

This is not merely a technical preference. It is a trust issue.

When a user asks why two pricing runs differ, conventions are one of the first places to look. If the run record does not contain convention information, the investigation becomes guesswork.

Market data and curve construction

Market data is not a single object.

A pricing run may depend on discount curves, forward curves, fixings, volatility surfaces, FX rates, credit curves, inflation curves, or other market inputs. Even in a narrow MVP, the market snapshot and curve construction process matter.

An audit-ready run should preserve:

• the market snapshot identifier,
• upload or acquisition time,
• valuation date,
• quote sources, if known,
• curve construction configuration,
• curve nodes,
• interpolation choices,
• extrapolation settings,
• bootstrapping warnings,
• missing or stale inputs,
• and generated curve artifacts.

The valuation date is particularly important. Many problems that appear to be pricing differences are actually date-context differences.

A run on the same trade and same nominal market quotes can produce a different result if the valuation date, fixing availability, settlement assumptions, or curve construction setup changes.

That is why market context should be first-class audit data, not background state.

Engine and model metadata

An audit-ready pricing run should record the engine that produced the result.

This includes both technical and quantitative metadata.

At minimum, the run should include:

• analytics engine version,
• code version or build identifier,
• container or deployment version,
• QuantLib version, if QuantLib is part of the engine,
• model selection,
• solver settings,
• numerical tolerances,
• random seed, if stochastic methods are used,
• and runtime warnings.

This is essential because software changes.

A pricing engine may receive bug fixes, model improvements, performance optimizations, dependency upgrades, or changes to numerical settings. Any of these may affect results.

If a result changes after a software update, the team should not be forced to guess whether the difference came from the portfolio, the market data, the conventions, or the engine. The run record should show exactly which engine version was used.

For deterministic workflows, the ideal standard is clear:

same inputs, same conventions, same engine version, same settings → same output within documented tolerances.

That statement is only meaningful if the run record stores all of those pieces.

Scenario definition

If the pricing run includes scenario analysis, the scenario definition must be part of the audit trail.

It is not enough to say that the run used a “parallel shift” or “stress scenario.” The run should preserve the actual scenario recipe.

That includes:

• scenario set name,
• scenario set version,
• risk factors affected,
• shift sizes,
• shift types,
• currencies or curves affected,
• whether shifts are absolute or relative,
• ordering of transformations,
• base market snapshot,
• and aggregation rules.

Scenario analysis can become difficult to audit because the number of outputs grows quickly. A single portfolio may be priced under many shifts. A scenario run may fan out into many child calculations. Some may succeed, some may fail, and some may need retries.

An audit-ready scenario run should therefore preserve both the parent run and the child runs.

The parent run records the scenario set, base inputs, and aggregation logic. The child runs record each individual pricing calculation. The final report links back to the full structure.

This makes it possible to answer:

Which scenario produced this loss?
Which trades contributed most?
Did every child calculation complete?
Were any partial results included?
Was this scenario recipe the same as the one used last week?

Without that structure, scenario analysis can become a collection of disconnected numbers.

Outputs and reports

Outputs should be structured, not just displayed.

An audit-ready run should preserve machine-readable outputs and human-readable reports. The report is useful for review and communication. The structured output is useful for comparison, integration, replay, and downstream analysis.

Depending on the run type, outputs may include:

• trade-level NPV,
• cashflows,
• accrued amounts,
• curve dependencies,
• PV01 or DV01,
• Greeks,
• scenario outputs,
• portfolio aggregations,
• bucketed sensitivities,
• validation warnings,
• pricing exceptions,
• and summary metrics.

Every export should link back to the run that produced it.

This is important because exports often travel outside the platform. A CSV file may be sent by email. A PDF may be shared with a client. A JSON file may be loaded into another internal system.

If the exported file does not contain a run reference and metadata manifest, then it can become detached from its origin.

An audit-ready export should therefore contain enough metadata to say:

This file came from run X, created at time T, using inputs A, B, C, and engine version D.

Logs, warnings, and exceptions

A clean output is not always a clean run.

An audit-ready run should preserve logs, warnings, and exceptions in a structured way.

This does not mean exposing every internal log line to the end user. It means recording enough diagnostic information to support later investigation.

Useful run diagnostics include:

• validation warnings,
• missing input warnings,
• curve construction warnings,
• fallback assumptions,
• unsupported trade messages,
• numerical convergence issues,
• partial failure information,
• retry attempts,
• timeout information,
• and engine warnings.

Warnings should not disappear just because the run completed.

A completed run with warnings is different from a completed run without warnings. Users should be able to see that difference.

This is especially important for portfolio runs. A portfolio-level summary can look successful even if a small number of trades failed, were skipped, or were priced with assumptions that require review.

Audit-ready systems should make partial success visible.

Access, tenant, and actor context

A pricing run should also preserve who did what.

At minimum, the run record should capture:

• organization or tenant,
• workspace,
• user or service actor,
• permissions context,
• time submitted,
• time completed,
• and any automated process that triggered the run.

For scheduled jobs or API-driven runs, the actor may not be a human clicking a button. It may be a service account, scheduled process, or integration.

That distinction matters.

If a report was created manually, users may expect one review process. If it was generated automatically through an API, they may expect another. If the run belongs to a particular workspace or client environment, access to the results must remain scoped correctly.

Audit-readiness is not only about calculation provenance. It is also about operational control.

Immutability

An audit-ready run should be immutable after completion.

That does not mean mistakes cannot be corrected. It means corrections should create new runs or new artifacts rather than overwriting the original record.

This principle is simple:

Preserve the historical record. Correct by appending, not by mutating.

If a portfolio was wrong, upload a corrected portfolio and run again. If a convention set changed, create a new version and run again. If a report needs a correction, generate a corrected report linked to the new run.

This avoids ambiguity.

Overwriting may feel convenient in the short term, but it creates problems later. Users may no longer know which version of a result was sent, reviewed, or used in a decision.

Immutable run records make the history explicit.

A practical audit-ready run checklist

A pricing run is audit-ready when it contains, or links to, the following:

Run identity

• run ID,
• workspace,
• tenant or organization,
• actor,
• run type,
• timestamps,
• status.

Input references

• portfolio artifact,
• market snapshot artifact,
• curve input artifact,
• fixing data,
• convention set version,
• pricing configuration,
• scenario set, if applicable.

Validation record

• schema version,
• validation status,
• validation warnings,
• rejected rows or trades,
• semantic validation checks,
• structured error report.

Market and curve context

• valuation date,
• curve construction settings,
• curve nodes,
• interpolation and extrapolation choices,
• bootstrapping warnings.

Engine metadata

• analytics engine version,
• code or container version,
• library versions,
• model selection,
• solver settings,
• tolerances,
• runtime warnings.

Scenario metadata

• scenario recipe,
• scenario version,
• shifts applied,
• affected risk factors,
• child run structure,
• aggregation rules.

Outputs

• trade-level results,
• portfolio aggregation,
• cashflows,
• sensitivities,
• scenario outputs,
• machine-readable result file,
• human-readable export,
• metadata manifest.

Provenance

• content hashes,
• immutable artifact links,
• logs,
• warnings,
• full traceability chain.

This checklist is not bureaucracy. It is what allows a team to trust the output later.

The goal is not just compliance

Audit-ready workflows are sometimes discussed as if they only matter for compliance or external review.

That is too narrow.

The same structure helps with ordinary day-to-day work.

It helps developers debug pricing discrepancies. It helps quants compare model changes. It helps risk users understand why portfolio numbers moved. It helps support teams investigate customer questions. It helps managers know whether a report was complete, partial, corrected, or superseded.

Auditability is not only a defensive feature.

It is a productivity feature.

A team that can reproduce and explain its analytics can move faster because it spends less time reconstructing what happened.

Closing thought

An audit-ready pricing run is not just a result table.

It is a complete, traceable calculation record.

It captures the identity of the run, the inputs, the validation state, the conventions, the market data, the engine version, the scenario definition, the outputs, the warnings, the actor, and the provenance chain.

That may sound like extra structure, but in practice it reduces confusion.

It turns pricing from a one-off calculation into a reliable workflow.

And for teams that depend on financial analytics, that reliability is often just as important as the pricing model itself.