Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions docs/economic-matrix.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
<!-- SPDX-FileCopyrightText: 2026 LibreSign contributors
SPDX-License-Identifier: AGPL-3.0-or-later -->

# Versioned economic parameter matrix

The economic matrix is a **private configuration file**, never an application source file or an image build input. Its path is explicitly provided at runtime. The public repository includes only `tests/Fixtures/economic-synthetic-v1.json`, containing fictional values.

## Contract

`schema_version: "2.0.0"`, `contract_id: "libresign.pricing.economic-parameters"`, `parameter_set_id`, `parameter_set_version`, `scope`, `approval_status`, `currency: "BRL"`, `models`, and `parameters` are mandatory. `models` has exactly the three delivery modalities. Each entry of the `parameters` list contains a unique stable ID, a decimal **string or null**, an explicit unit, a source reference, and `approval_status`.

Only `parameters` is the numerical source of truth. The earlier private research contract (schema 1.0.0) included duplicate `simulation_assumptions` and `scenario_results`; these are **not accepted** by the new contract. Migrate values and provenance into the parameter list privately. Recompute scenarios; do not carry over their calculated output as configuration.

Unknown (`null`) means the value has not been measured. It is never coerced to zero. Binary floating point numbers, duplicates, missing units and invalid versions fail validation.

`scope: "SYNTHETIC_ONLY"` and `approval_status: "research_only"` are appropriate for public fictional fixtures. `scope: "PRIVATE_ECONOMICS"` can only be selected from a **private, explicitly mounted file**. Commercial authorization additionally requires the catalog status, evidence and validity interval, and approval of every referenced parameter; approval is not inferred from the file's location.

The PHP engine defines formulas and known parameter IDs, not prices or economic assumptions. Values can be revised by distributing a new private, reviewed version, without changing the code. A SHA-256 digest identifies the exact bytes used for any result.

No actual costs, rates, client names, source paths, secrets, or accounting datasets belong in public fixtures, GitHub PRs, logs or Docker images. Catalog review and approval are distinct from deploying a new PHP revision.
194 changes: 194 additions & 0 deletions src/Domain/EconomicParameterMatrix.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,194 @@
<?php

// SPDX-FileCopyrightText: 2026 LibreSign contributors
// SPDX-License-Identifier: AGPL-3.0-or-later

declare(strict_types=1);

namespace LibreSign\Pricing\Domain;

use Brick\Math\BigDecimal;

final readonly class EconomicParameterMatrix
{
/** @var array<string, array<string, mixed>> */
private array $index;

/** @param array<string, mixed> $document */
private function __construct(private array $document, private string $sha256)
{
if (($document['schema_version'] ?? null) !== '2.0.0'
|| ($document['contract_id'] ?? null) !== 'libresign.pricing.economic-parameters'
|| ($document['currency'] ?? null) !== 'BRL'
|| !in_array($document['scope'] ?? null, ['SYNTHETIC_ONLY', 'PRIVATE_ECONOMICS'], true)
|| !in_array($document['approval_status'] ?? null, ['research_only', 'approved_for_quotes'], true)
|| !self::identifier($document['parameter_set_id'] ?? null)
|| !self::identifier($document['parameter_set_version'] ?? null)
|| !is_array($document['models'] ?? null)
|| !is_array($document['parameters'] ?? null)
|| !array_is_list($document['parameters'])
|| array_key_exists('simulation_assumptions', $document)
|| array_key_exists('scenario_results', $document)) {
throw new \InvalidArgumentException('Invalid economic parameter matrix contract.');
}

if ($document['scope'] === 'SYNTHETIC_ONLY' && $document['approval_status'] !== 'research_only') {
throw new \InvalidArgumentException('Synthetic parameters cannot be approved.');
}

foreach (['cloud', 'managed', 'customer_infrastructure'] as $model) {
$configuration = $document['models'][$model] ?? null;
if (!is_array($configuration)
|| !in_array($configuration['billing_basis'] ?? null, ['monthly', 'project', 'project_with_optional_recurring'], true)
|| ($configuration['parameter_prefix'] ?? null) !== 'simulation.'.$model) {
throw new \InvalidArgumentException('Invalid model configuration.');
}
}

$index = [];
foreach ($document['parameters'] as $parameter) {
if (!is_array($parameter)
|| !self::identifier($parameter['id'] ?? null)
|| !is_string($parameter['unit'] ?? null)
|| $parameter['unit'] === ''
|| !is_string($parameter['source'] ?? null)
|| $parameter['source'] === ''
|| !in_array($parameter['approval_status'] ?? null, ['not_approved_for_commercial_use', 'approved_for_commercial_use'], true)
|| !array_key_exists('value', $parameter)
|| !self::decimalOrNull($parameter['value'])) {
throw new \InvalidArgumentException('Invalid economic parameter.');
}
$id = $parameter['id'];
if (isset($index[$id])) {
throw new \InvalidArgumentException('Duplicate economic parameter.');
}
if ($document['scope'] === 'SYNTHETIC_ONLY'
&& $parameter['approval_status'] === 'approved_for_commercial_use') {
throw new \InvalidArgumentException('Synthetic parameter cannot be commercially approved.');
}
$index[$id] = $parameter;
}
if ($index === []) {
throw new \InvalidArgumentException('Economic parameter matrix is empty.');
}
$this->index = $index;
}

public static function fromJson(string $content): self
{
if (strlen($content) > 1048576) {
throw new \InvalidArgumentException('Economic parameter matrix is too large.');
}
try {
$data = json_decode($content, true, 32, JSON_THROW_ON_ERROR);
} catch (\JsonException $exception) {
throw new \InvalidArgumentException('Malformed economic parameter matrix.', 0, $exception);
}
if (!is_array($data) || array_is_list($data)) {
throw new \InvalidArgumentException('Economic parameter matrix must be a JSON object.');
}
return new self($data, hash('sha256', $content));
}

public function decimal(string $id, string $unit): ?BigDecimal
{
$parameter = $this->index[$id] ?? null;
if ($parameter === null || $parameter['unit'] !== $unit) {
throw new \InvalidArgumentException('Missing parameter or incompatible unit: '.$id);
}
$value = $parameter['value'];
return $value === null ? null : BigDecimal::of($value);
}

public function requireDecimal(string $id, string $unit): BigDecimal
{
return $this->decimal($id, $unit)
?? throw new \DomainException('Required economic parameter is unknown: '.$id);
}

/** @return array{billing_basis: string, parameter_prefix: string} */
public function model(string $id): array
{
$configuration = $this->document['models'][$id] ?? null;
if (!is_array($configuration)) {
throw new \InvalidArgumentException('Unknown pricing model.');
}
return [
'billing_basis' => $configuration['billing_basis'],
'parameter_prefix' => $configuration['parameter_prefix'],
];
}

/** @param list<string> $parameterIds */
public function quoteAllowed(array $parameterIds, string $onDate): bool
{
if ($this->document['scope'] !== 'PRIVATE_ECONOMICS'
|| $this->document['approval_status'] !== 'approved_for_quotes'
|| !self::identifier($this->document['approved_by'] ?? null)
|| !self::identifier($this->document['approval_reference'] ?? null)
|| !self::validDate($onDate)
|| !self::validDate($this->document['effective_from'] ?? null)
|| !self::validDate($this->document['effective_until'] ?? null)
|| $onDate < $this->document['effective_from']
|| $onDate > $this->document['effective_until']) {
return false;
}
foreach ($parameterIds as $id) {
$parameter = $this->index[$id] ?? null;
if ($parameter === null
|| $parameter['value'] === null
|| $parameter['approval_status'] !== 'approved_for_commercial_use') {
return false;
}
}
return true;
}

public function version(): string
{
return $this->document['parameter_set_version'];
}

public function fingerprint(): string
{
return $this->sha256;
}

public function scope(): string
{
return $this->document['scope'];
}

/** @return array<string, mixed> */
public function metadata(): array
{
return [
'id' => $this->document['parameter_set_id'],
'version' => $this->version(),
'sha256' => $this->fingerprint(),
'scope' => $this->scope(),
'approval_status' => $this->document['approval_status'],
];
}

private static function decimalOrNull(mixed $value): bool
{
return $value === null
|| (is_string($value)
&& preg_match('/^(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,8})?$/D', $value) === 1);
}

private static function identifier(mixed $value): bool
{
return is_string($value)
&& preg_match('/^[A-Za-z][A-Za-z0-9._-]{0,127}$/D', $value) === 1;
}

private static function validDate(mixed $value): bool
{
if (!is_string($value) || preg_match('/^(\d{4})-(\d{2})-(\d{2})$/D', $value, $matches) !== 1) {
return false;
}
return checkdate((int) $matches[2], (int) $matches[3], (int) $matches[1]);
}
}
33 changes: 33 additions & 0 deletions src/Infrastructure/EconomicMatrixLoader.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
<?php

// SPDX-FileCopyrightText: 2026 LibreSign contributors
// SPDX-License-Identifier: AGPL-3.0-or-later

declare(strict_types=1);

namespace LibreSign\Pricing\Infrastructure;

use LibreSign\Pricing\Domain\EconomicParameterMatrix;

final readonly class EconomicMatrixLoader
{
public function __construct(private string $filename)
{
}

public function load(): EconomicParameterMatrix
{
if ($this->filename === '') {
throw new CatalogUnavailable('An economic matrix path must be explicitly configured.');
}
$content = @file_get_contents($this->filename);
if (!is_string($content)) {
throw new CatalogUnavailable('Economic matrix unavailable.');
}
try {
return EconomicParameterMatrix::fromJson($content);
} catch (\InvalidArgumentException $exception) {
throw new CatalogUnavailable('Economic matrix invalid.', 0, $exception);
}
}
}
Loading
Loading