diff --git a/docs/economic-matrix.md b/docs/economic-matrix.md new file mode 100644 index 0000000..0457b94 --- /dev/null +++ b/docs/economic-matrix.md @@ -0,0 +1,20 @@ + + +# 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. diff --git a/src/Domain/EconomicParameterMatrix.php b/src/Domain/EconomicParameterMatrix.php new file mode 100644 index 0000000..4f2ba8b --- /dev/null +++ b/src/Domain/EconomicParameterMatrix.php @@ -0,0 +1,194 @@ +> */ + private array $index; + + /** @param array $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 $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 */ + 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]); + } +} diff --git a/src/Infrastructure/EconomicMatrixLoader.php b/src/Infrastructure/EconomicMatrixLoader.php new file mode 100644 index 0000000..8654d29 --- /dev/null +++ b/src/Infrastructure/EconomicMatrixLoader.php @@ -0,0 +1,33 @@ +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); + } + } +} diff --git a/tests/Fixtures/economic-synthetic-v1.json b/tests/Fixtures/economic-synthetic-v1.json new file mode 100644 index 0000000..a6b1ddb --- /dev/null +++ b/tests/Fixtures/economic-synthetic-v1.json @@ -0,0 +1,197 @@ +{ + "contract_id": "libresign.pricing.economic-parameters", + "schema_version": "2.0.0", + "parameter_set_id": "fictional-economic-v1", + "parameter_set_version": "fictional-v1", + "scope": "SYNTHETIC_ONLY", + "approval_status": "research_only", + "currency": "BRL", + "approved_by": null, + "approval_reference": null, + "effective_from": null, + "effective_until": null, + "models": { + "cloud": { + "billing_basis": "monthly", + "parameter_prefix": "simulation.cloud" + }, + "managed": { + "billing_basis": "monthly", + "parameter_prefix": "simulation.managed" + }, + "customer_infrastructure": { + "billing_basis": "project_with_optional_recurring", + "parameter_prefix": "simulation.customer_infrastructure" + } + }, + "parameters": [ + { + "id": "simulation.cloud.fixed_pool", + "value": "120.00", + "unit": "BRL/period", + "source": "FICTIONAL_TEST_FIXTURE", + "approval_status": "not_approved_for_commercial_use" + }, + { + "id": "simulation.cloud.variable_unit", + "value": "5.00", + "unit": "BRL/customer_period", + "source": "FICTIONAL_TEST_FIXTURE", + "approval_status": "not_approved_for_commercial_use" + }, + { + "id": "simulation.cloud.hours_unit", + "value": "0.50", + "unit": "hours/customer_period", + "source": "FICTIONAL_TEST_FIXTURE", + "approval_status": "not_approved_for_commercial_use" + }, + { + "id": "simulation.cloud.full_hour", + "value": "12.00", + "unit": "BRL/hour", + "source": "FICTIONAL_TEST_FIXTURE", + "approval_status": "not_approved_for_commercial_use" + }, + { + "id": "simulation.cloud.collective_hour", + "value": "18.00", + "unit": "BRL/hour", + "source": "FICTIONAL_TEST_FIXTURE", + "approval_status": "not_approved_for_commercial_use" + }, + { + "id": "simulation.cloud.setup_hours", + "value": "1.00", + "unit": "hour/customer", + "source": "FICTIONAL_TEST_FIXTURE", + "approval_status": "not_approved_for_commercial_use" + }, + { + "id": "simulation.cloud.capacity", + "value": "10", + "unit": "customer", + "source": "FICTIONAL_TEST_FIXTURE", + "approval_status": "not_approved_for_commercial_use" + }, + { + "id": "simulation.managed.fixed_pool", + "value": "180.00", + "unit": "BRL/period", + "source": "FICTIONAL_TEST_FIXTURE", + "approval_status": "not_approved_for_commercial_use" + }, + { + "id": "simulation.managed.variable_unit", + "value": "30.00", + "unit": "BRL/customer_period", + "source": "FICTIONAL_TEST_FIXTURE", + "approval_status": "not_approved_for_commercial_use" + }, + { + "id": "simulation.managed.hours_unit", + "value": "2.00", + "unit": "hours/customer_period", + "source": "FICTIONAL_TEST_FIXTURE", + "approval_status": "not_approved_for_commercial_use" + }, + { + "id": "simulation.managed.full_hour", + "value": "12.00", + "unit": "BRL/hour", + "source": "FICTIONAL_TEST_FIXTURE", + "approval_status": "not_approved_for_commercial_use" + }, + { + "id": "simulation.managed.collective_hour", + "value": "18.00", + "unit": "BRL/hour", + "source": "FICTIONAL_TEST_FIXTURE", + "approval_status": "not_approved_for_commercial_use" + }, + { + "id": "simulation.managed.setup_hours", + "value": "4.00", + "unit": "hour/customer", + "source": "FICTIONAL_TEST_FIXTURE", + "approval_status": "not_approved_for_commercial_use" + }, + { + "id": "simulation.managed.capacity", + "value": "6", + "unit": "customer", + "source": "FICTIONAL_TEST_FIXTURE", + "approval_status": "not_approved_for_commercial_use" + }, + { + "id": "simulation.customer_infrastructure.fixed_pool", + "value": "60.00", + "unit": "BRL/period", + "source": "FICTIONAL_TEST_FIXTURE", + "approval_status": "not_approved_for_commercial_use" + }, + { + "id": "simulation.customer_infrastructure.variable_unit", + "value": "15.00", + "unit": "BRL/customer_period", + "source": "FICTIONAL_TEST_FIXTURE", + "approval_status": "not_approved_for_commercial_use" + }, + { + "id": "simulation.customer_infrastructure.hours_unit", + "value": "3.00", + "unit": "hours/customer_period", + "source": "FICTIONAL_TEST_FIXTURE", + "approval_status": "not_approved_for_commercial_use" + }, + { + "id": "simulation.customer_infrastructure.full_hour", + "value": "12.00", + "unit": "BRL/hour", + "source": "FICTIONAL_TEST_FIXTURE", + "approval_status": "not_approved_for_commercial_use" + }, + { + "id": "simulation.customer_infrastructure.collective_hour", + "value": "18.00", + "unit": "BRL/hour", + "source": "FICTIONAL_TEST_FIXTURE", + "approval_status": "not_approved_for_commercial_use" + }, + { + "id": "simulation.customer_infrastructure.setup_hours", + "value": "8.00", + "unit": "hour/customer", + "source": "FICTIONAL_TEST_FIXTURE", + "approval_status": "not_approved_for_commercial_use" + }, + { + "id": "simulation.customer_infrastructure.capacity", + "value": "4", + "unit": "customer", + "source": "FICTIONAL_TEST_FIXTURE", + "approval_status": "not_approved_for_commercial_use" + }, + { + "id": "simulation.tax", + "value": "0.05", + "unit": "fraction", + "source": "FICTIONAL_TEST_FIXTURE", + "approval_status": "not_approved_for_commercial_use" + }, + { + "id": "simulation.default", + "value": "0.02", + "unit": "fraction", + "source": "FICTIONAL_TEST_FIXTURE", + "approval_status": "not_approved_for_commercial_use" + }, + { + "id": "simulation.target_margin", + "value": "0.15", + "unit": "fraction", + "source": "FICTIONAL_TEST_FIXTURE", + "approval_status": "not_approved_for_commercial_use" + } + ] +} diff --git a/tests/Unit/EconomicMatrixLoaderTest.php b/tests/Unit/EconomicMatrixLoaderTest.php new file mode 100644 index 0000000..84110c3 --- /dev/null +++ b/tests/Unit/EconomicMatrixLoaderTest.php @@ -0,0 +1,109 @@ +matrix(); + self::assertSame('fictional-v1', $matrix->version()); + self::assertSame('SYNTHETIC_ONLY', $matrix->scope()); + self::assertSame('5.00', (string) $matrix->requireDecimal('simulation.cloud.variable_unit', 'BRL/customer_period')); + self::assertFalse($matrix->quoteAllowed(['simulation.cloud.variable_unit'], '2026-11-05')); + self::assertCount(64, str_split($matrix->fingerprint())); + + $data = self::fixture(); + $data['parameters'][0]['value'] = null; + $incomplete = EconomicParameterMatrix::fromJson(json_encode($data, JSON_THROW_ON_ERROR)); + self::assertNull($incomplete->decimal('simulation.cloud.fixed_pool', 'BRL/period')); + $this->expectException(\DomainException::class); + $incomplete->requireDecimal('simulation.cloud.fixed_pool', 'BRL/period'); + } + + public function testFileIsNeverSelectedImplicitly(): void + { + $this->expectException(CatalogUnavailable::class); + (new EconomicMatrixLoader(''))->load(); + } + + public function testAbsentPrivateFileFailsClosed(): void + { + $this->expectException(CatalogUnavailable::class); + (new EconomicMatrixLoader('/nonexistent/private/economic-matrix.json'))->load(); + } + + public function testDuplicateIdentifiersAreRejected(): void + { + $data = self::fixture(); + $data['parameters'][] = $data['parameters'][0]; + $this->expectException(\InvalidArgumentException::class); + EconomicParameterMatrix::fromJson(json_encode($data, JSON_THROW_ON_ERROR)); + } + + public function testFloatingPointInputsAreRejected(): void + { + $data = self::fixture(); + $data['parameters'][0]['value'] = 1.234; + $this->expectException(\InvalidArgumentException::class); + EconomicParameterMatrix::fromJson(json_encode($data, JSON_THROW_ON_ERROR)); + } + + public function testIncompatibleUnitsAreRejected(): void + { + $this->expectException(\InvalidArgumentException::class); + $this->matrix()->decimal('simulation.cloud.variable_unit', 'BRL/hour'); + } + + public function testSyntheticApprovalEscalationIsRejected(): void + { + $data = self::fixture(); + $data['approval_status'] = 'approved_for_quotes'; + $this->expectException(\InvalidArgumentException::class); + EconomicParameterMatrix::fromJson(json_encode($data, JSON_THROW_ON_ERROR)); + } + + public function testDuplicateSourcesOfEconomicValuesAreRejected(): void + { + $data = self::fixture(); + $data['simulation_assumptions'] = ['cloud' => ['fixed_pool' => '999.00']]; + $this->expectException(\InvalidArgumentException::class); + EconomicParameterMatrix::fromJson(json_encode($data, JSON_THROW_ON_ERROR)); + } + + public function testChangedParametersChangeFingerprint(): void + { + $data = self::fixture(); + $data['parameters'][0]['value'] = '121.00'; + self::assertNotSame( + $this->matrix()->fingerprint(), + EconomicParameterMatrix::fromJson(json_encode($data, JSON_THROW_ON_ERROR))->fingerprint(), + ); + } + + /** @return array */ + private static function fixture(): array + { + return json_decode( + (string) file_get_contents(dirname(__DIR__, 2).'/tests/Fixtures/economic-synthetic-v1.json'), + true, + 32, + JSON_THROW_ON_ERROR, + ); + } + + private function matrix(): EconomicParameterMatrix + { + return (new EconomicMatrixLoader(dirname(__DIR__, 2).'/tests/Fixtures/economic-synthetic-v1.json'))->load(); + } +}