Copyright	(c) 2026 Jared Tobin
License	MIT
Maintainer	Jared Tobin <jared@ppad.tech>
Safe Haskell	Safe-Inferred
Language	Haskell2010

Censor.Runner.Manifest

Contents

Types
Parsing
Layout validation

Description

A declarative battery for the censor CLI: run-wide defaults and a list of cases, each naming a target symbol and the workspace layout to drive it with. One invocation opens the library once and emits one censor/report-v3 object covering every case.

The format is line-oriented. Blank lines and # comments are ignored; every other line is either a run-wide directive (key value) or a case (case NAME key=value...):

# ppad-secp256k1 scalar surfaces
meter          wall
alpha          1e-6
budget         20000
warmup         500
target-prefix  censor_target_
workspace      128

case mul       secret=0:32
case sign      workspace=96 secret=0:32 public=32:32
case ecdh      secret=0:32 context=32:32
case inv       secret=0:32 replicates=3

A case's target symbol is target-prefix ++ its name unless target= overrides it outright.

Synopsis

data Manifest = Manifest {
- mfDefaults :: !Defaults
- mfCases :: ![ManifestCase]
}
data Defaults = Defaults {
- dfMeter :: !(Maybe String)
- dfAlpha :: !(Maybe Double)
- dfBudget :: !(Maybe Int)
- dfWarmup :: !(Maybe Int)
- dfBatch :: !(Maybe BatchSpec)
- dfMargin :: !(Maybe Double)
- dfSeed :: !(Maybe Word64)
- dfOrderSeed :: !(Maybe Word64)
- dfPrefix :: !(Maybe String)
- dfWorkspace :: !(Maybe Int)
- dfFamilyAlpha :: !(Maybe Bool)
}
data ManifestCase = ManifestCase {
- mcId :: !String
- mcName :: !String
- mcTarget :: !String
- mcWorkspace :: !Int
- mcSecret :: ![Range]
- mcPublic :: ![Range]
- mcContext :: ![Range]
- mcBatch :: !(Maybe BatchSpec)
- mcReplicates :: !Int
}
data Range = Range {
- rangeOff :: !Int
- rangeLen :: !Int
}
data BatchSpec
- = BatchFixed !Int
- | BatchAuto
parseManifest :: String -> Either String Manifest
emptyDefaults :: Defaults
readRange :: String -> Maybe Range
readSeed :: String -> Maybe Word64
checkLayout :: Int -> [Range] -> [Range] -> [Range] -> Maybe String

Types

data Manifest Source #

A parsed manifest.

Constructors

Manifest
Fields mfDefaults :: !Defaults mfCases :: ![ManifestCase]

Instances

Instances details

Show Manifest Source #
Instance details Defined in Censor.Runner.Manifest Methods showsPrec :: Int -> Manifest -> ShowS # show :: Manifest -> String # showList :: [Manifest] -> ShowS #
Eq Manifest Source #
Instance details Defined in Censor.Runner.Manifest Methods (==) :: Manifest -> Manifest -> Bool # (/=) :: Manifest -> Manifest -> Bool #

data Defaults Source #

Run-wide directives. Every field is optional; Nothing defers to the runner's own default (or a command-line override).

Constructors

Defaults

Fields

dfMeter :: !(Maybe String)
dfAlpha :: !(Maybe Double)
dfBudget :: !(Maybe Int)
dfWarmup :: !(Maybe Int)
dfBatch :: !(Maybe BatchSpec)
dfMargin :: !(Maybe Double)
relative interval-null margin (see cfgMargin).
dfSeed :: !(Maybe Word64)
seeds the input samplers.
dfOrderSeed :: !(Maybe Word64)
seeds the A/B order bit. Left unset in a checked-in manifest: the default is fresh OS entropy per run, and the resolved value is reported for replay.
dfPrefix :: !(Maybe String)
dfWorkspace :: !(Maybe Int)
dfFamilyAlpha :: !(Maybe Bool)
when set, run every expanded cell at alpha / M (M being the number of cells) so the battery tests at alpha family-wise, rather than merely reporting the union bound.

Instances

Instances details

Show Defaults Source #
Instance details Defined in Censor.Runner.Manifest Methods showsPrec :: Int -> Defaults -> ShowS # show :: Defaults -> String # showList :: [Defaults] -> ShowS #
Eq Defaults Source #
Instance details Defined in Censor.Runner.Manifest Methods (==) :: Defaults -> Defaults -> Bool # (/=) :: Defaults -> Defaults -> Bool #

data ManifestCase Source #

One case: a display name, the symbol to resolve, the workspace layout, and how many times to replicate it.

Constructors

ManifestCase

Fields

mcId :: !String
the case token as written in the manifest, before any label= override. This is the case's identity: the runner mixes it into the run-wide seed to give each case its own fixed secret.
Kept apart from mcName so that renaming a case for presentation does not change the experiment it runs.
mcName :: !String
the display name: mcId, or whatever label= set. Used for rendering only.
mcTarget :: !String
mcWorkspace :: !Int
mcSecret :: ![Range]
mcPublic :: ![Range]
mcContext :: ![Range]
ranges redrawn once per pair and written identically into both classes: a fresh public input shared by the pair (see fixVsRandomCtx).
mcBatch :: !(Maybe BatchSpec)
mcReplicates :: !Int
how many independent fixed secrets to run this case against, each its own case row. One pinned secret only asks whether that secret times differently from random; replicating guards against an unlucky draw.

Instances

Instances details

Show ManifestCase Source #
Instance details Defined in Censor.Runner.Manifest Methods showsPrec :: Int -> ManifestCase -> ShowS # show :: ManifestCase -> String # showList :: [ManifestCase] -> ShowS #
Eq ManifestCase Source #
Instance details Defined in Censor.Runner.Manifest Methods (==) :: ManifestCase -> ManifestCase -> Bool # (/=) :: ManifestCase -> ManifestCase -> Bool #

data Range Source #

A byte range within the workspace: off:len.

Constructors

Range
Fields rangeOff :: !Int rangeLen :: !Int

Instances

Instances details

Show Range Source #
Instance details Defined in Censor.Runner.Manifest Methods showsPrec :: Int -> Range -> ShowS # show :: Range -> String # showList :: [Range] -> ShowS #
Eq Range Source #
Instance details Defined in Censor.Runner.Manifest Methods (==) :: Range -> Range -> Bool # (/=) :: Range -> Range -> Bool #

data BatchSpec Source #

How a case picks its cfgBatch. Foreign targets genuinely recompute on every repetition, so BatchAuto is meaningful here in a way it is not for a pure Haskell target.

Constructors

BatchFixed !Int	pin the batch.
BatchAuto	calibrate it per case.

Instances

Instances details

Show BatchSpec Source #
Instance details Defined in Censor.Runner.Manifest Methods showsPrec :: Int -> BatchSpec -> ShowS # show :: BatchSpec -> String # showList :: [BatchSpec] -> ShowS #
Eq BatchSpec Source #
Instance details Defined in Censor.Runner.Manifest Methods (==) :: BatchSpec -> BatchSpec -> Bool # (/=) :: BatchSpec -> BatchSpec -> Bool #

Parsing

parseManifest :: String -> Either String Manifest Source #

Parse a manifest. Returns a message naming the offending line on failure.

Case order is preserved. A manifest with no cases is an error: it is far more likely a typo than an intent.

emptyDefaults :: Defaults Source #

All directives unset.

readRange :: String -> Maybe Range Source #

Read an off:len byte range, with off >= 0 and len > 0.

readSeed :: String -> Maybe Word64 Source #

Read a hex Word64, with or without a 0x prefix.

Layout validation

checkLayout Source #

Arguments

:: Int	workspace bytes
-> [Range]	secret ranges
-> [Range]	public ranges
-> [Range]	context ranges
-> Maybe String

Check a workspace layout: every declared range must fit inside the workspace, and the three roles must be pairwise disjoint. Nothing when the layout is sound; otherwise a message naming the first problem, for the caller to place in context.

Both entry points validate through this — a manifest case and the single-case command line — so the two cannot drift on what they accept.

Overlapping roles are rejected rather than resolved by precedence. A byte is pinned in class A only (mcSecret), pinned in both for the run (mcPublic), refreshed per pair in both (mcContext), or freshly random in each class; asking for two of those at once has no coherent reading, and whichever overlay happened to land last would silently pick one. That is how a public range could mask the context it overlapped, turning a per-pair refresh into a constant without saying so.