Appendix: preference model specification

The canonical computation is the exported compute function in the Portfolio Compass module. It receives a complete input object containing the relative weights and candidate alternatives, validates that object and returns a deterministic output object. The research reproducer imports this same module in the JavaScript runtime. The manuscript does not maintain a parallel finance or preference implementation in another language. Its frozen outputs are receipts of that canonical computation, while the scalar bindings identify the exact input or output field behind every printed numerical result.

The input contains the fixed criterion keys cost, impact, readiness and risk. Each alternative supplies a name and a value for every criterion. Relative weights are supplied under those same keys. The schema rejects additional fields, missing required values and malformed types. Numerical inputs must be finite and lie within the declared bounds. A small nonzero magnitude below the explicit precision floor is rejected rather than silently rounded to zero. The complete machine-readable schema is distributed with the app, so exact validation limits remain inspectable without relying on abbreviated prose.

The precision rule has a narrow purpose. It avoids accepting negligible nonzero values that can create unstable ratios or misleading representations in shared numerical routines. It is not a claim about the precision of cost estimates or rating evidence. A real estimate can be much less certain than the numerical type permits. The app's structural validation and the committee's evidence acceptance therefore remain separate. Passing the schema establishes that the computation can operate on the supplied values; it does not establish that those values are meaningful for the decision.

Candidate names must be nonempty within the allowed length and unique after the shared uniqueness check. Names organise display and export identity; they do not affect the weighted total. They can affect the order used to display equal totals because the engine uses a name comparison as its deterministic secondary sort. A reviewer should treat that secondary ordering as presentation. The substantive preference remains tied. Renaming equal-scoring candidates cannot create a justified investment priority.

The engine sums the supplied relative weights and rejects a vector whose total is zero. It divides each supplied weight by that total to obtain the normalised vector. Thus multiplying all raw weights by a common positive factor preserves the normalised tradeoff, provided the input remains within the schema. The normalisation does not remove the need for an authorised elicitation rationale. It only makes the common scale of the supplied vector irrelevant to the weighted aggregation.

The transformed criterion values occupy the unit interval, with the favourable endpoint at the upper end. The score multiplies their normalised weighted sum by the app's common preference-point scale. Each criterion contribution uses the same multiplication for its own term. The output therefore contains a total and a transparent contribution ledger. The point scale is a display convention. It does not establish probability, utility in money or a proportionate measure of organisational benefit. The underlying interpretation depends on the validity of the rubrics and tradeoffs.

Equal raw values on a criterion produce the same midpoint contribution for every candidate. That criterion does not distinguish the ordering, although it remains visible in every total. This convention avoids division by a collapsed range and makes the absence of discriminatory information explicit. It does not say that the shared performance is acceptable or average in an external population. The common position is a numerical treatment within the present comparison. Eligibility or absolute performance requirements must be assessed separately.

Raw Pareto membership is computed independently of the weights. For a candidate to be dominated, another candidate must be no worse on every raw criterion under the declared directions and strictly better on at least one. The engine checks the supplied candidates against one another and returns the names that are not dominated. It uses no preference threshold, probabilistic tolerance or inferred importance. Equality on every raw value leaves neither candidate strictly dominating the other, even if their names differ.

The distinction matters when a raw criterion has no weight. The additive score ignores that criterion by design, but the Pareto check still includes it. A candidate can therefore share a weighted total with a raw dominator. The engine retains both statements instead of inserting a hidden preference. The committee must interpret whether the zero weight expresses authorised indifference, a concern handled as a gate or a mistake in elicitation. The app's warning and ledger make the issue reviewable without deciding it on behalf of the user.

The sensitivity routine operates on the normalised vector. For each criterion, it applies the fixed upward and downward percentage-point shift, caps the changed weight within the unit interval and rescales the others to fill the remainder in their existing proportions. When the starting vector assigns all weight to that criterion, the released remainder is distributed equally across the other criteria because no existing positive proportion is available. That fallback is explicitly disclosed. It is a computational convention for the selected challenge, not an inferred preference.

Each sensitivity row retains the changed criterion, requested shift, resulting weight, preferred display entry, leading score, position of the original display leader and full ordering. The leader-retention summary counts how often the original display name remains first across those selected tests. It does not assess every preference vector and does not resolve tied-score substance. The close-contest appendix therefore shows the actual rows rather than interpreting the summary as confidence. The full frozen output contains the routine's details for replication.

The engine does not calculate feasibility constraints or optimise a combination. There is no budget field, package-benefit function, dependency graph, cashflow schedule or probability distribution in this input schema. Adding such concepts to a narrative around the result does not make them represented by the computation. The specification is deliberately explicit about absence because it determines what a recommendation can claim. A funding or staged programme decision needs a further method whose inputs and operations fit those relationships.

Replication begins with the frozen input rather than the output summary. Import the input under the supported model version, run the canonical compute function and compare the resulting structure and scalar values with the archived output. The research audit performs this comparison and checks the binding pointers. A printed value is linked to an existing scalar, not recalculated by an author script. The author scripts only select fields, assemble explicitly written prose and organise exhibits. That separation prevents a manuscript formula from drifting away from the live app.

The claims ledger records whether a scalar comes from supplied input or computed output, its scope and the block in which it is used. Every numerical study remains explicitly illustrative. Reciprocal links let the audit check that a block's tokens correspond to the intended claims and that claims point back to their printed uses. Unprinted output leaves remain archived with a reason rather than being misrepresented as published findings. The ledger provides traceability, while the reader-facing exhibit explains the consequence in ordinary language.

A model-linked chart uses the same frozen scalar pointers. The deterministic plotting helper performs coordinate placement only; it does not implement preference mathematics. An adjacent plot specification records the selected outputs, drawing range and series. The audit can redraw the asset from those pointers and compare it. Lines in the selected-weight diagnostic connect discrete challenge points for visual comparison; they do not estimate the full preference boundary between them. A caption must preserve that distinction so a graphical connector is not mistaken for an unperformed sensitivity sweep.

Check the exports according to their receiving use. Reimport a scenario to verify that the supplied values and supported version survive the round trip. Inspect the CSV as a tabular record, including the neutralisation of user-controlled cells that might otherwise be interpreted as formulae. Read the printable brief to see whether a reviewer can recover the contribution explanation and its method limits. These checks ask different questions, so success in one does not substitute for another. The numerical files remain linked to the separate charter and minutes. Optional local persistence determines retention in the platform, while the institution determines retention of its authoritative decision record.

Reproducibility can be checked without claiming correctness of every supplied proposition. The automated tests cover positive, negative, boundary and invariant cases, including independent expected fixtures. Real browser journeys exercise editing, invalid input, comparison, export, import, narrow layouts and state retention. Those checks support implementation behaviour. Independent review must still challenge the manuscript's reasoning, source scope and decision limits. The edition should distinguish those evidence layers rather than using a green test receipt as a universal quality certificate.