867 lines
39 KiB
Python
867 lines
39 KiB
Python
"""Bounded, task-only optimization proposals for Baseline 1.1.
|
|
|
|
This module deliberately has no configuration or policy write adapter. Its only
|
|
effect boundary is ``submit_task``, supplied by the authenticated root service.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import hashlib
|
|
import json
|
|
import math
|
|
from dataclasses import dataclass
|
|
from pathlib import Path
|
|
import re
|
|
import sqlite3
|
|
import time
|
|
from typing import Any, Callable, Mapping
|
|
|
|
|
|
ENVELOPE_SCHEMA = "aios.optimization-envelope.v1"
|
|
PROPOSAL_SCHEMA = "aios.optimization-proposal.v1"
|
|
TASK_REQUEST_SCHEMA = "aios.optimization-task-request.v1"
|
|
|
|
_IDENTIFIER = re.compile(r"[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}")
|
|
_DIGEST = re.compile(r"sha256:[0-9a-f]{64}")
|
|
|
|
# An envelope may narrow these limits but cannot introduce another path or
|
|
# expand a range. Every entry describes a low-risk operational tuning knob.
|
|
_HARD_PARAMETER_LIMITS: dict[str, tuple[float, float, bool]] = {
|
|
"retry.max_attempts": (1, 10, True),
|
|
"retry.backoff_seconds": (0, 60, False),
|
|
"backoff.initial_seconds": (0, 60, False),
|
|
"backoff.maximum_seconds": (0.1, 600, False),
|
|
"routing.candidate_weight_percent": (0, 25, False),
|
|
"routing.weight_percent": (0, 25, False),
|
|
"evidence_reuse.max_age_seconds": (0, 3600, True),
|
|
"evidence_reuse.ttl_seconds": (0, 3600, True),
|
|
"timeout.operation_seconds": (0.1, 300, False),
|
|
"timeout.seconds": (0.1, 300, False),
|
|
"poll.interval_seconds": (0.1, 300, False),
|
|
"notification_dedup.window_seconds": (0, 3600, True),
|
|
"test_selection.optional_sample_percent": (1, 100, False),
|
|
"test_selection.optional_percentage": (1, 100, False),
|
|
}
|
|
_NON_PRODUCTION_ENVIRONMENTS = frozenset({"development", "test", "staging", "canary"})
|
|
|
|
|
|
class OptimizationError(RuntimeError):
|
|
"""A fail-closed optimization boundary error with a stable code."""
|
|
|
|
def __init__(self, code: str):
|
|
self.code = code
|
|
super().__init__(code)
|
|
|
|
|
|
def canonical_json_bytes(value: Any) -> bytes:
|
|
try:
|
|
return json.dumps(
|
|
value,
|
|
sort_keys=True,
|
|
separators=(",", ":"),
|
|
ensure_ascii=False,
|
|
allow_nan=False,
|
|
).encode("utf-8")
|
|
except (TypeError, ValueError) as exc:
|
|
raise OptimizationError("OPTIMIZATION_DOCUMENT_NOT_CANONICAL") from exc
|
|
|
|
|
|
def _digest(value: Any) -> str:
|
|
return "sha256:" + hashlib.sha256(canonical_json_bytes(value)).hexdigest()
|
|
|
|
|
|
def _number(value: Any, code: str, *, minimum: float | None = None,
|
|
maximum: float | None = None) -> int | float:
|
|
if isinstance(value, bool) or not isinstance(value, (int, float)):
|
|
raise OptimizationError(code)
|
|
if not math.isfinite(float(value)):
|
|
raise OptimizationError(code)
|
|
if minimum is not None and value < minimum:
|
|
raise OptimizationError(code)
|
|
if maximum is not None and value > maximum:
|
|
raise OptimizationError(code)
|
|
return value
|
|
|
|
|
|
def _identifier(value: Any, code: str) -> str:
|
|
if not isinstance(value, str) or _IDENTIFIER.fullmatch(value) is None:
|
|
raise OptimizationError(code)
|
|
return value
|
|
|
|
|
|
def _unique_identifiers(value: Any, code: str, *, maximum: int = 256) -> tuple[str, ...]:
|
|
if not isinstance(value, (list, tuple)) or len(value) > maximum:
|
|
raise OptimizationError(code)
|
|
items = tuple(_identifier(item, code) for item in value)
|
|
if len(set(items)) != len(items):
|
|
raise OptimizationError(code)
|
|
return items
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class ParameterRange:
|
|
minimum: int | float
|
|
maximum: int | float
|
|
integer: bool
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class QualityFloor:
|
|
direction: str
|
|
threshold: int | float
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class PromotionRules:
|
|
objective_metric: str
|
|
minimum_improvement: int | float
|
|
mandatory_tests: tuple[str, ...]
|
|
mandatory_quality_gates: tuple[str, ...]
|
|
required_receipt_schema: str
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class OptimizationEnvelope:
|
|
schema: str
|
|
envelope_id: str
|
|
tenant_id: str
|
|
allowed_parameters: Mapping[str, ParameterRange]
|
|
allowed_components: tuple[str, ...]
|
|
allowed_environments: tuple[str, ...]
|
|
max_change_size: int
|
|
max_compute_budget: int | float
|
|
quality_floor: Mapping[str, QualityFloor]
|
|
rollback_requirement: bool
|
|
promotion_rules: PromotionRules
|
|
source_config_digest: str
|
|
key_id: str
|
|
signature: str
|
|
|
|
@classmethod
|
|
def from_dict(
|
|
cls,
|
|
data: Mapping[str, Any],
|
|
*,
|
|
verify_envelope: Callable[[str, bytes, str], bool] | None,
|
|
) -> "OptimizationEnvelope":
|
|
"""Parse a trusted-config envelope after authenticating its exact bytes.
|
|
|
|
``verify_envelope`` is intentionally mandatory. The caller cannot mark
|
|
a document trusted with a boolean or construct an unrestricted envelope.
|
|
"""
|
|
if verify_envelope is None or not callable(verify_envelope):
|
|
raise OptimizationError("OPTIMIZATION_ENVELOPE_VERIFIER_REQUIRED")
|
|
if not isinstance(data, Mapping):
|
|
raise OptimizationError("OPTIMIZATION_ENVELOPE_INVALID")
|
|
required = {
|
|
"schema", "envelope_id", "tenant_id", "allowed_parameters",
|
|
"allowed_components", "allowed_environments", "max_change_size",
|
|
"max_compute_budget", "quality_floor", "rollback_requirement",
|
|
"promotion_rules", "source_config_digest", "key_id", "signature",
|
|
}
|
|
if set(data) != required:
|
|
raise OptimizationError("OPTIMIZATION_ENVELOPE_FIELDS_INVALID")
|
|
unsigned = dict(data)
|
|
signature = unsigned.pop("signature")
|
|
key_id = data.get("key_id")
|
|
if not isinstance(signature, str) or not signature or not isinstance(key_id, str):
|
|
raise OptimizationError("OPTIMIZATION_ENVELOPE_SIGNATURE_INVALID")
|
|
try:
|
|
verified = verify_envelope(key_id, canonical_json_bytes(unsigned), signature)
|
|
except Exception as exc:
|
|
raise OptimizationError("OPTIMIZATION_ENVELOPE_SIGNATURE_INVALID") from exc
|
|
if verified is not True:
|
|
raise OptimizationError("OPTIMIZATION_ENVELOPE_SIGNATURE_INVALID")
|
|
|
|
if data["schema"] != ENVELOPE_SCHEMA:
|
|
raise OptimizationError("OPTIMIZATION_ENVELOPE_SCHEMA_INVALID")
|
|
envelope_id = _identifier(data["envelope_id"], "OPTIMIZATION_ENVELOPE_ID_INVALID")
|
|
tenant_id = _identifier(data["tenant_id"], "OPTIMIZATION_TENANT_INVALID")
|
|
if not _DIGEST.fullmatch(str(data["source_config_digest"])):
|
|
raise OptimizationError("OPTIMIZATION_SOURCE_CONFIG_DIGEST_INVALID")
|
|
key_id = _identifier(key_id, "OPTIMIZATION_ENVELOPE_KEY_ID_INVALID")
|
|
|
|
raw_parameters = data["allowed_parameters"]
|
|
if not isinstance(raw_parameters, Mapping) or not raw_parameters or len(raw_parameters) > 16:
|
|
raise OptimizationError("OPTIMIZATION_ALLOWED_PARAMETERS_INVALID")
|
|
parameters: dict[str, ParameterRange] = {}
|
|
for path, raw_rule in raw_parameters.items():
|
|
if path not in _HARD_PARAMETER_LIMITS:
|
|
raise OptimizationError("OPTIMIZATION_PARAMETER_PATH_FORBIDDEN")
|
|
if not isinstance(raw_rule, Mapping) or not {"minimum", "maximum"} <= set(raw_rule):
|
|
raise OptimizationError("OPTIMIZATION_PARAMETER_RANGE_INVALID")
|
|
if set(raw_rule) - {"minimum", "maximum", "integer"}:
|
|
raise OptimizationError("OPTIMIZATION_PARAMETER_RANGE_INVALID")
|
|
hard_min, hard_max, hard_integer = _HARD_PARAMETER_LIMITS[path]
|
|
minimum = _number(raw_rule["minimum"], "OPTIMIZATION_PARAMETER_RANGE_INVALID")
|
|
maximum = _number(raw_rule["maximum"], "OPTIMIZATION_PARAMETER_RANGE_INVALID")
|
|
integer = raw_rule.get("integer", hard_integer)
|
|
if type(integer) is not bool or minimum > maximum:
|
|
raise OptimizationError("OPTIMIZATION_PARAMETER_RANGE_INVALID")
|
|
if minimum < hard_min or maximum > hard_max or (hard_integer and not integer):
|
|
raise OptimizationError("OPTIMIZATION_PARAMETER_RANGE_TOO_BROAD")
|
|
if integer and (type(minimum) is not int or type(maximum) is not int):
|
|
raise OptimizationError("OPTIMIZATION_PARAMETER_RANGE_INVALID")
|
|
parameters[path] = ParameterRange(minimum, maximum, integer)
|
|
|
|
components = _unique_identifiers(
|
|
data["allowed_components"], "OPTIMIZATION_COMPONENTS_INVALID", maximum=32
|
|
)
|
|
environments = _unique_identifiers(
|
|
data["allowed_environments"], "OPTIMIZATION_ENVIRONMENTS_INVALID", maximum=4
|
|
)
|
|
if not components or not environments or not set(environments) <= _NON_PRODUCTION_ENVIRONMENTS:
|
|
raise OptimizationError("OPTIMIZATION_ENVIRONMENTS_INVALID")
|
|
max_change_size = _number(
|
|
data["max_change_size"], "OPTIMIZATION_CHANGE_SIZE_INVALID", minimum=1, maximum=16
|
|
)
|
|
if type(max_change_size) is not int:
|
|
raise OptimizationError("OPTIMIZATION_CHANGE_SIZE_INVALID")
|
|
max_compute_budget = _number(
|
|
data["max_compute_budget"],
|
|
"OPTIMIZATION_COMPUTE_BUDGET_INVALID",
|
|
minimum=0.001,
|
|
maximum=10_000,
|
|
)
|
|
|
|
raw_quality = data["quality_floor"]
|
|
if not isinstance(raw_quality, Mapping) or not raw_quality or len(raw_quality) > 16:
|
|
raise OptimizationError("OPTIMIZATION_QUALITY_FLOOR_INVALID")
|
|
quality: dict[str, QualityFloor] = {}
|
|
for metric, raw_rule in raw_quality.items():
|
|
metric = _identifier(metric, "OPTIMIZATION_QUALITY_METRIC_INVALID")
|
|
if not isinstance(raw_rule, Mapping) or set(raw_rule) != {"direction", "threshold"}:
|
|
raise OptimizationError("OPTIMIZATION_QUALITY_FLOOR_INVALID")
|
|
if raw_rule["direction"] not in {"higher", "lower"}:
|
|
raise OptimizationError("OPTIMIZATION_QUALITY_DIRECTION_INVALID")
|
|
threshold = _number(
|
|
raw_rule["threshold"], "OPTIMIZATION_QUALITY_FLOOR_INVALID",
|
|
minimum=-1e12, maximum=1e12,
|
|
)
|
|
quality[metric] = QualityFloor(raw_rule["direction"], threshold)
|
|
|
|
if type(data["rollback_requirement"]) is not bool:
|
|
raise OptimizationError("OPTIMIZATION_ROLLBACK_REQUIREMENT_INVALID")
|
|
raw_promotion = data["promotion_rules"]
|
|
promotion_fields = {
|
|
"objective_metric", "minimum_improvement", "mandatory_tests",
|
|
"mandatory_quality_gates", "required_receipt_schema",
|
|
}
|
|
if not isinstance(raw_promotion, Mapping) or set(raw_promotion) != promotion_fields:
|
|
raise OptimizationError("OPTIMIZATION_PROMOTION_RULES_INVALID")
|
|
objective = _identifier(
|
|
raw_promotion["objective_metric"], "OPTIMIZATION_OBJECTIVE_METRIC_INVALID"
|
|
)
|
|
if objective not in quality:
|
|
raise OptimizationError("OPTIMIZATION_OBJECTIVE_METRIC_INVALID")
|
|
minimum_improvement = _number(
|
|
raw_promotion["minimum_improvement"],
|
|
"OPTIMIZATION_MINIMUM_IMPROVEMENT_INVALID",
|
|
minimum=0,
|
|
maximum=1e12,
|
|
)
|
|
mandatory_tests = _unique_identifiers(
|
|
raw_promotion["mandatory_tests"], "OPTIMIZATION_MANDATORY_TESTS_INVALID"
|
|
)
|
|
mandatory_gates = _unique_identifiers(
|
|
raw_promotion["mandatory_quality_gates"], "OPTIMIZATION_MANDATORY_GATES_INVALID"
|
|
)
|
|
if not mandatory_tests or not mandatory_gates:
|
|
raise OptimizationError("OPTIMIZATION_PROMOTION_RULES_INVALID")
|
|
receipt_schema = _identifier(
|
|
raw_promotion["required_receipt_schema"], "OPTIMIZATION_RECEIPT_SCHEMA_INVALID"
|
|
)
|
|
if not receipt_schema.startswith("aios."):
|
|
raise OptimizationError("OPTIMIZATION_RECEIPT_SCHEMA_INVALID")
|
|
promotion = PromotionRules(
|
|
objective, minimum_improvement, mandatory_tests, mandatory_gates, receipt_schema
|
|
)
|
|
return cls(
|
|
ENVELOPE_SCHEMA, envelope_id, tenant_id, parameters, components,
|
|
environments, max_change_size, max_compute_budget, quality,
|
|
data["rollback_requirement"], promotion, data["source_config_digest"],
|
|
key_id, signature,
|
|
)
|
|
|
|
|
|
_PROPOSAL_REQUIRED = {
|
|
"schema", "proposal_id", "envelope_id", "tenant_id", "component",
|
|
"environment", "changes", "compute_budget", "tests", "quality_gates",
|
|
"baseline_metrics", "rollback_plan",
|
|
}
|
|
|
|
|
|
def validate_proposal(envelope: OptimizationEnvelope, proposal: Mapping[str, Any]) -> dict:
|
|
"""Return a canonical candidate constrained by ``envelope``."""
|
|
if not isinstance(envelope, OptimizationEnvelope):
|
|
raise OptimizationError("OPTIMIZATION_ENVELOPE_REQUIRED")
|
|
if not isinstance(proposal, Mapping):
|
|
raise OptimizationError("OPTIMIZATION_PROPOSAL_INVALID")
|
|
allowed_fields = _PROPOSAL_REQUIRED | {"evidence_reuse"}
|
|
if set(proposal) - allowed_fields or not _PROPOSAL_REQUIRED <= set(proposal):
|
|
raise OptimizationError("OPTIMIZATION_PROPOSAL_FIELDS_INVALID")
|
|
if proposal["schema"] != PROPOSAL_SCHEMA:
|
|
raise OptimizationError("OPTIMIZATION_PROPOSAL_SCHEMA_INVALID")
|
|
proposal_id = _identifier(proposal["proposal_id"], "OPTIMIZATION_PROPOSAL_ID_INVALID")
|
|
if proposal["envelope_id"] != envelope.envelope_id:
|
|
raise OptimizationError("OPTIMIZATION_ENVELOPE_BINDING_MISMATCH")
|
|
if proposal["tenant_id"] != envelope.tenant_id:
|
|
raise OptimizationError("OPTIMIZATION_PROPOSAL_TENANT_MISMATCH")
|
|
component = _identifier(proposal["component"], "OPTIMIZATION_COMPONENT_INVALID")
|
|
if component not in envelope.allowed_components:
|
|
raise OptimizationError("OPTIMIZATION_COMPONENT_FORBIDDEN")
|
|
environment = _identifier(proposal["environment"], "OPTIMIZATION_ENVIRONMENT_INVALID")
|
|
if environment not in envelope.allowed_environments:
|
|
raise OptimizationError("OPTIMIZATION_ENVIRONMENT_FORBIDDEN")
|
|
|
|
raw_changes = proposal["changes"]
|
|
if not isinstance(raw_changes, list) or not raw_changes or len(raw_changes) > envelope.max_change_size:
|
|
raise OptimizationError("OPTIMIZATION_CHANGE_SIZE_EXCEEDED")
|
|
changes: list[dict[str, Any]] = []
|
|
paths: set[str] = set()
|
|
for change in raw_changes:
|
|
if not isinstance(change, Mapping) or set(change) != {"path", "value"}:
|
|
raise OptimizationError("OPTIMIZATION_CHANGE_INVALID")
|
|
path = change["path"]
|
|
if not isinstance(path, str) or path not in envelope.allowed_parameters:
|
|
raise OptimizationError("OPTIMIZATION_PARAMETER_PATH_FORBIDDEN")
|
|
if path in paths:
|
|
raise OptimizationError("OPTIMIZATION_PARAMETER_DUPLICATE")
|
|
paths.add(path)
|
|
rule = envelope.allowed_parameters[path]
|
|
value = _number(change["value"], "OPTIMIZATION_PARAMETER_VALUE_INVALID")
|
|
if rule.integer and type(value) is not int:
|
|
raise OptimizationError("OPTIMIZATION_PARAMETER_VALUE_INVALID")
|
|
if value < rule.minimum or value > rule.maximum:
|
|
raise OptimizationError("OPTIMIZATION_PARAMETER_OUT_OF_RANGE")
|
|
changes.append({"path": path, "value": value})
|
|
|
|
compute_budget = _number(
|
|
proposal["compute_budget"],
|
|
"OPTIMIZATION_COMPUTE_BUDGET_EXCEEDED",
|
|
minimum=0.001,
|
|
maximum=float(envelope.max_compute_budget),
|
|
)
|
|
tests = _unique_identifiers(proposal["tests"], "OPTIMIZATION_TESTS_INVALID")
|
|
gates = _unique_identifiers(proposal["quality_gates"], "OPTIMIZATION_QUALITY_GATES_INVALID")
|
|
for mandatory in envelope.promotion_rules.mandatory_tests:
|
|
if mandatory not in tests:
|
|
raise OptimizationError("OPTIMIZATION_MANDATORY_TEST_MISSING")
|
|
for mandatory in envelope.promotion_rules.mandatory_quality_gates:
|
|
if mandatory not in gates:
|
|
raise OptimizationError("OPTIMIZATION_MANDATORY_GATE_MISSING")
|
|
|
|
raw_baseline = proposal["baseline_metrics"]
|
|
if not isinstance(raw_baseline, Mapping) or set(raw_baseline) != set(envelope.quality_floor):
|
|
raise OptimizationError("OPTIMIZATION_BASELINE_METRICS_INVALID")
|
|
baseline = {
|
|
metric: _number(raw_baseline[metric], "OPTIMIZATION_BASELINE_METRICS_INVALID")
|
|
for metric in sorted(raw_baseline)
|
|
}
|
|
|
|
rollback_plan = proposal["rollback_plan"]
|
|
if envelope.rollback_requirement:
|
|
if (
|
|
not isinstance(rollback_plan, Mapping)
|
|
or set(rollback_plan) != {"strategy", "reference"}
|
|
or rollback_plan.get("strategy") != "restore_previous_values"
|
|
):
|
|
raise OptimizationError("OPTIMIZATION_ROLLBACK_PLAN_REQUIRED")
|
|
_identifier(rollback_plan.get("reference"), "OPTIMIZATION_ROLLBACK_PLAN_INVALID")
|
|
normalized_rollback: dict[str, str] | None = {
|
|
"strategy": "restore_previous_values",
|
|
"reference": rollback_plan["reference"],
|
|
}
|
|
else:
|
|
if rollback_plan is not None:
|
|
raise OptimizationError("OPTIMIZATION_ROLLBACK_PLAN_INVALID")
|
|
normalized_rollback = None
|
|
|
|
normalized_evidence = None
|
|
if "evidence_reuse" in proposal:
|
|
evidence = proposal["evidence_reuse"]
|
|
if not isinstance(evidence, Mapping) or set(evidence) != {"scope", "evidence_ids"}:
|
|
raise OptimizationError("OPTIMIZATION_EVIDENCE_REUSE_INVALID")
|
|
expected_scope = {
|
|
"tenant_id": envelope.tenant_id,
|
|
"component": component,
|
|
"environment": environment,
|
|
}
|
|
if evidence["scope"] != expected_scope:
|
|
raise OptimizationError("OPTIMIZATION_EVIDENCE_SCOPE_MISMATCH")
|
|
evidence_ids = _unique_identifiers(
|
|
evidence["evidence_ids"], "OPTIMIZATION_EVIDENCE_REUSE_INVALID", maximum=128
|
|
)
|
|
normalized_evidence = {"scope": expected_scope, "evidence_ids": list(evidence_ids)}
|
|
|
|
normalized = {
|
|
"schema": PROPOSAL_SCHEMA,
|
|
"proposal_id": proposal_id,
|
|
"envelope_id": envelope.envelope_id,
|
|
"tenant_id": envelope.tenant_id,
|
|
"component": component,
|
|
"environment": environment,
|
|
"changes": changes,
|
|
"compute_budget": float(compute_budget),
|
|
"tests": list(tests),
|
|
"quality_gates": list(gates),
|
|
"baseline_metrics": baseline,
|
|
"rollback_plan": normalized_rollback,
|
|
}
|
|
if normalized_evidence is not None:
|
|
normalized["evidence_reuse"] = normalized_evidence
|
|
if len(canonical_json_bytes(normalized)) > 65_536:
|
|
raise OptimizationError("OPTIMIZATION_PROPOSAL_TOO_LARGE")
|
|
return normalized
|
|
|
|
|
|
class OptimizationController:
|
|
"""Durable proposal state machine whose only external effect is task admission."""
|
|
|
|
def __init__(
|
|
self,
|
|
path: str | Path,
|
|
envelope: OptimizationEnvelope,
|
|
submit_task: Callable[[Mapping[str, Any]], Mapping[str, Any]],
|
|
*,
|
|
verify_receipt: Callable[[Mapping[str, Any]], bool],
|
|
):
|
|
if not isinstance(envelope, OptimizationEnvelope):
|
|
raise OptimizationError("OPTIMIZATION_ENVELOPE_REQUIRED")
|
|
if not callable(submit_task):
|
|
raise OptimizationError("OPTIMIZATION_TASK_SUBMITTER_REQUIRED")
|
|
if not callable(verify_receipt):
|
|
raise OptimizationError("OPTIMIZATION_RECEIPT_VERIFIER_REQUIRED")
|
|
self.path = Path(path)
|
|
self.path.parent.mkdir(parents=True, exist_ok=True)
|
|
self.envelope = envelope
|
|
self.submit_task = submit_task
|
|
self.verify_receipt = verify_receipt
|
|
self._initialize()
|
|
|
|
def _connect(self) -> sqlite3.Connection:
|
|
connection = sqlite3.connect(self.path, timeout=30)
|
|
connection.row_factory = sqlite3.Row
|
|
connection.execute("PRAGMA foreign_keys=ON")
|
|
return connection
|
|
|
|
def _initialize(self) -> None:
|
|
with self._connect() as connection:
|
|
connection.execute("PRAGMA journal_mode=WAL")
|
|
connection.execute(
|
|
"""
|
|
CREATE TABLE IF NOT EXISTS optimization_proposals (
|
|
proposal_id TEXT PRIMARY KEY,
|
|
tenant_id TEXT NOT NULL,
|
|
subject_id TEXT NOT NULL,
|
|
grant_id TEXT NOT NULL,
|
|
mission_id TEXT NOT NULL,
|
|
envelope_id TEXT NOT NULL,
|
|
proposal_digest TEXT NOT NULL,
|
|
proposal_json TEXT NOT NULL,
|
|
status TEXT NOT NULL,
|
|
evaluation_task_id TEXT,
|
|
promotion_task_id TEXT,
|
|
baseline_json TEXT NOT NULL,
|
|
candidate_json TEXT,
|
|
effect_json TEXT,
|
|
evaluation_json TEXT,
|
|
receipt_json TEXT,
|
|
error_code TEXT,
|
|
created_at REAL NOT NULL,
|
|
updated_at REAL NOT NULL
|
|
)
|
|
"""
|
|
)
|
|
|
|
def _context(self, value: Mapping[str, Any]) -> dict[str, str]:
|
|
if not isinstance(value, Mapping):
|
|
raise OptimizationError("OPTIMIZATION_AUTHENTICATED_CONTEXT_REQUIRED")
|
|
fields = ("tenant_id", "subject_id", "grant_id", "mission_id", "service_identity")
|
|
try:
|
|
context = {
|
|
field: _identifier(value[field], "OPTIMIZATION_AUTHENTICATED_CONTEXT_INVALID")
|
|
for field in fields
|
|
}
|
|
except KeyError as exc:
|
|
raise OptimizationError("OPTIMIZATION_AUTHENTICATED_CONTEXT_REQUIRED") from exc
|
|
if context["service_identity"] != "aios-root-service":
|
|
raise OptimizationError("OPTIMIZATION_ROOT_SERVICE_REQUIRED")
|
|
if context["tenant_id"] != self.envelope.tenant_id:
|
|
raise OptimizationError("OPTIMIZATION_CONTEXT_TENANT_MISMATCH")
|
|
return context
|
|
|
|
def _row(self, proposal_id: str) -> sqlite3.Row:
|
|
with self._connect() as connection:
|
|
row = connection.execute(
|
|
"SELECT * FROM optimization_proposals WHERE proposal_id=?", (proposal_id,)
|
|
).fetchone()
|
|
if row is None:
|
|
raise OptimizationError("OPTIMIZATION_PROPOSAL_NOT_FOUND")
|
|
return row
|
|
|
|
def _authorized_row(self, proposal_id: str, context: Mapping[str, Any]) -> sqlite3.Row:
|
|
checked = self._context(context)
|
|
row = self._row(_identifier(proposal_id, "OPTIMIZATION_PROPOSAL_ID_INVALID"))
|
|
if row["tenant_id"] != checked["tenant_id"]:
|
|
raise OptimizationError("OPTIMIZATION_CONTEXT_TENANT_MISMATCH")
|
|
if row["subject_id"] != checked["subject_id"]:
|
|
raise OptimizationError("OPTIMIZATION_CONTEXT_SUBJECT_MISMATCH")
|
|
if row["grant_id"] != checked["grant_id"]:
|
|
raise OptimizationError("OPTIMIZATION_CONTEXT_GRANT_MISMATCH")
|
|
if row["mission_id"] != checked["mission_id"]:
|
|
raise OptimizationError("OPTIMIZATION_CONTEXT_MISSION_MISMATCH")
|
|
return row
|
|
|
|
@staticmethod
|
|
def _decode(value: str | None) -> Any:
|
|
return None if value is None else json.loads(value)
|
|
|
|
def _record(self, row: sqlite3.Row) -> dict:
|
|
proposal = self._decode(row["proposal_json"])
|
|
result = dict(proposal)
|
|
result.update(
|
|
{
|
|
"proposal_id": row["proposal_id"],
|
|
"proposal_digest": row["proposal_digest"],
|
|
"status": row["status"],
|
|
"evaluation_task_id": row["evaluation_task_id"],
|
|
"promotion_task_id": row["promotion_task_id"],
|
|
"baseline_metrics": self._decode(row["baseline_json"]),
|
|
"candidate_metrics": self._decode(row["candidate_json"]),
|
|
"effect_comparison": self._decode(row["effect_json"]),
|
|
"error_code": row["error_code"],
|
|
}
|
|
)
|
|
return result
|
|
|
|
def get_proposal(self, proposal_id: str, *, authenticated_context: Mapping[str, Any]) -> dict:
|
|
return self._record(self._authorized_row(proposal_id, authenticated_context))
|
|
|
|
def _persist_invalid(self, proposal: Mapping[str, Any], context: Mapping[str, str],
|
|
error: OptimizationError) -> None:
|
|
proposal_id = proposal.get("proposal_id")
|
|
tenant_id = proposal.get("tenant_id")
|
|
if (
|
|
not isinstance(proposal_id, str)
|
|
or _IDENTIFIER.fullmatch(proposal_id) is None
|
|
or tenant_id != self.envelope.tenant_id
|
|
):
|
|
return
|
|
try:
|
|
encoded = canonical_json_bytes(proposal)
|
|
except OptimizationError:
|
|
return
|
|
if len(encoded) > 65_536:
|
|
return
|
|
digest = "sha256:" + hashlib.sha256(encoded).hexdigest()
|
|
baseline = proposal.get("baseline_metrics")
|
|
if not isinstance(baseline, Mapping):
|
|
baseline = {}
|
|
now = time.time()
|
|
with self._connect() as connection:
|
|
connection.execute(
|
|
"""
|
|
INSERT OR IGNORE INTO optimization_proposals
|
|
(proposal_id,tenant_id,subject_id,grant_id,mission_id,envelope_id,
|
|
proposal_digest,proposal_json,status,baseline_json,error_code,created_at,updated_at)
|
|
VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?)
|
|
""",
|
|
(
|
|
proposal_id, self.envelope.tenant_id, context["subject_id"],
|
|
context["grant_id"], context["mission_id"], self.envelope.envelope_id,
|
|
digest, encoded.decode("utf-8"), "STOPPED_INVALID",
|
|
canonical_json_bytes(baseline).decode("utf-8"), error.code, now, now,
|
|
),
|
|
)
|
|
|
|
def propose(self, proposal: Mapping[str, Any], *, authenticated_context: Mapping[str, Any]) -> dict:
|
|
context = self._context(authenticated_context)
|
|
try:
|
|
normalized = validate_proposal(self.envelope, proposal)
|
|
except OptimizationError as exc:
|
|
if isinstance(proposal, Mapping):
|
|
self._persist_invalid(proposal, context, exc)
|
|
raise
|
|
proposal_digest = _digest(normalized)
|
|
proposal_id = normalized["proposal_id"]
|
|
now = time.time()
|
|
encoded = canonical_json_bytes(normalized).decode("utf-8")
|
|
with self._connect() as connection:
|
|
existing = connection.execute(
|
|
"SELECT * FROM optimization_proposals WHERE proposal_id=?", (proposal_id,)
|
|
).fetchone()
|
|
if existing is not None:
|
|
if existing["proposal_digest"] != proposal_digest:
|
|
raise OptimizationError("OPTIMIZATION_PROPOSAL_ID_CONFLICT")
|
|
if (
|
|
existing["tenant_id"] != context["tenant_id"]
|
|
or existing["subject_id"] != context["subject_id"]
|
|
or existing["grant_id"] != context["grant_id"]
|
|
or existing["mission_id"] != context["mission_id"]
|
|
):
|
|
raise OptimizationError("OPTIMIZATION_CONTEXT_BINDING_MISMATCH")
|
|
if existing["status"] != "PROPOSAL_RECORDED":
|
|
return self._record(existing)
|
|
else:
|
|
connection.execute(
|
|
"""
|
|
INSERT INTO optimization_proposals
|
|
(proposal_id,tenant_id,subject_id,grant_id,mission_id,envelope_id,
|
|
proposal_digest,proposal_json,status,baseline_json,created_at,updated_at)
|
|
VALUES(?,?,?,?,?,?,?,?,?,?,?,?)
|
|
""",
|
|
(
|
|
proposal_id, context["tenant_id"], context["subject_id"],
|
|
context["grant_id"], context["mission_id"], self.envelope.envelope_id,
|
|
proposal_digest, encoded, "PROPOSAL_RECORDED",
|
|
canonical_json_bytes(normalized["baseline_metrics"]).decode("utf-8"),
|
|
now, now,
|
|
),
|
|
)
|
|
|
|
requested_task_id = f"optimization-evaluate-{proposal_id}"
|
|
task_request = {
|
|
"schema": TASK_REQUEST_SCHEMA,
|
|
"task_id": requested_task_id,
|
|
"action": "evaluate",
|
|
"tenant_id": context["tenant_id"],
|
|
"subject_id": context["subject_id"],
|
|
"grant_id": context["grant_id"],
|
|
"mission_id": context["mission_id"],
|
|
"proposal_id": proposal_id,
|
|
"proposal_digest": proposal_digest,
|
|
"component": normalized["component"],
|
|
"environment": normalized["environment"],
|
|
"compute_budget": normalized["compute_budget"],
|
|
}
|
|
try:
|
|
receipt = self.submit_task(task_request)
|
|
if not isinstance(receipt, Mapping):
|
|
raise OptimizationError("OPTIMIZATION_TASK_SUBMISSION_INVALID")
|
|
task_id = _identifier(
|
|
receipt.get("task_id"), "OPTIMIZATION_TASK_SUBMISSION_INVALID"
|
|
)
|
|
except Exception as exc:
|
|
with self._connect() as connection:
|
|
connection.execute(
|
|
"UPDATE optimization_proposals SET status=?,error_code=?,updated_at=? "
|
|
"WHERE proposal_id=? AND status='PROPOSAL_RECORDED'",
|
|
("STOPPED_SUBMISSION_FAILED", "OPTIMIZATION_TASK_SUBMISSION_FAILED", time.time(), proposal_id),
|
|
)
|
|
if isinstance(exc, OptimizationError):
|
|
raise
|
|
raise OptimizationError("OPTIMIZATION_TASK_SUBMISSION_FAILED") from exc
|
|
with self._connect() as connection:
|
|
connection.execute(
|
|
"UPDATE optimization_proposals SET status=?,evaluation_task_id=?,updated_at=? "
|
|
"WHERE proposal_id=? AND status='PROPOSAL_RECORDED'",
|
|
("EVALUATION_SUBMITTED", task_id, time.time(), proposal_id),
|
|
)
|
|
return self.get_proposal(proposal_id, authenticated_context=context)
|
|
|
|
def _trusted_receipt(self, receipt: Any) -> Mapping[str, Any]:
|
|
if not isinstance(receipt, Mapping):
|
|
raise OptimizationError("OPTIMIZATION_RECEIPT_INVALID")
|
|
try:
|
|
trusted = self.verify_receipt(receipt)
|
|
except Exception as exc:
|
|
raise OptimizationError("OPTIMIZATION_RECEIPT_UNTRUSTED") from exc
|
|
if trusted is not True:
|
|
raise OptimizationError("OPTIMIZATION_RECEIPT_UNTRUSTED")
|
|
return receipt
|
|
|
|
def record_evaluation(
|
|
self,
|
|
proposal_id: str,
|
|
evaluation: Mapping[str, Any],
|
|
*,
|
|
authenticated_context: Mapping[str, Any],
|
|
) -> dict:
|
|
row = self._authorized_row(proposal_id, authenticated_context)
|
|
if row["status"] != "EVALUATION_SUBMITTED":
|
|
raise OptimizationError("OPTIMIZATION_EVALUATION_STATE_INVALID")
|
|
if not isinstance(evaluation, Mapping) or set(evaluation) != {
|
|
"candidate_metrics", "compute_used", "tests_passed",
|
|
"quality_gates_passed", "receipt",
|
|
}:
|
|
raise OptimizationError("OPTIMIZATION_EVALUATION_INVALID")
|
|
result_body = {key: evaluation[key] for key in evaluation if key != "receipt"}
|
|
receipt = self._trusted_receipt(evaluation["receipt"])
|
|
required_receipt = {
|
|
"schema", "task_id", "proposal_id", "proposal_digest", "action",
|
|
"success", "result_digest", "key_id", "signature",
|
|
}
|
|
if set(receipt) != required_receipt:
|
|
raise OptimizationError("OPTIMIZATION_RECEIPT_INVALID")
|
|
if receipt["schema"] != self.envelope.promotion_rules.required_receipt_schema:
|
|
raise OptimizationError("OPTIMIZATION_RECEIPT_SCHEMA_MISMATCH")
|
|
if receipt["task_id"] != row["evaluation_task_id"]:
|
|
raise OptimizationError("OPTIMIZATION_RECEIPT_TASK_MISMATCH")
|
|
if receipt["proposal_id"] != row["proposal_id"]:
|
|
raise OptimizationError("OPTIMIZATION_RECEIPT_PROPOSAL_MISMATCH")
|
|
if receipt["proposal_digest"] != row["proposal_digest"]:
|
|
raise OptimizationError("OPTIMIZATION_RECEIPT_PROPOSAL_DIGEST_MISMATCH")
|
|
if receipt["action"] != "evaluate" or receipt["success"] is not True:
|
|
raise OptimizationError("OPTIMIZATION_RECEIPT_RESULT_INVALID")
|
|
if receipt["result_digest"] != _digest(result_body):
|
|
raise OptimizationError("OPTIMIZATION_RECEIPT_RESULT_DIGEST_MISMATCH")
|
|
|
|
proposal = self._decode(row["proposal_json"])
|
|
compute_used = _number(
|
|
evaluation["compute_used"], "OPTIMIZATION_EVALUATION_BUDGET_EXCEEDED", minimum=0
|
|
)
|
|
if compute_used > proposal["compute_budget"] or compute_used > self.envelope.max_compute_budget:
|
|
status = "STOPPED_BUDGET_EXCEEDED"
|
|
error_code = "OPTIMIZATION_EVALUATION_BUDGET_EXCEEDED"
|
|
return self._store_evaluation(row, evaluation, receipt, {}, status, error_code)
|
|
tests_passed = _unique_identifiers(
|
|
evaluation["tests_passed"], "OPTIMIZATION_EVALUATION_TESTS_INVALID"
|
|
)
|
|
gates_passed = _unique_identifiers(
|
|
evaluation["quality_gates_passed"], "OPTIMIZATION_EVALUATION_GATES_INVALID"
|
|
)
|
|
if not set(self.envelope.promotion_rules.mandatory_tests) <= set(tests_passed):
|
|
return self._store_evaluation(
|
|
row, evaluation, receipt, {}, "STOPPED_MANDATORY_TEST_FAILED",
|
|
"OPTIMIZATION_MANDATORY_TEST_FAILED",
|
|
)
|
|
if not set(self.envelope.promotion_rules.mandatory_quality_gates) <= set(gates_passed):
|
|
return self._store_evaluation(
|
|
row, evaluation, receipt, {}, "STOPPED_MANDATORY_GATE_FAILED",
|
|
"OPTIMIZATION_MANDATORY_GATE_FAILED",
|
|
)
|
|
raw_candidate = evaluation["candidate_metrics"]
|
|
if not isinstance(raw_candidate, Mapping) or set(raw_candidate) != set(self.envelope.quality_floor):
|
|
raise OptimizationError("OPTIMIZATION_CANDIDATE_METRICS_INVALID")
|
|
candidate = {
|
|
metric: _number(raw_candidate[metric], "OPTIMIZATION_CANDIDATE_METRICS_INVALID")
|
|
for metric in sorted(raw_candidate)
|
|
}
|
|
baseline = self._decode(row["baseline_json"])
|
|
effect: dict[str, float] = {}
|
|
quality_regression = False
|
|
for metric in sorted(self.envelope.quality_floor):
|
|
rule = self.envelope.quality_floor[metric]
|
|
if rule.direction == "higher":
|
|
delta = float(candidate[metric]) - float(baseline[metric])
|
|
below_floor = candidate[metric] < rule.threshold
|
|
else:
|
|
delta = float(baseline[metric]) - float(candidate[metric])
|
|
below_floor = candidate[metric] > rule.threshold
|
|
effect[metric] = round(delta, 12)
|
|
quality_regression = quality_regression or below_floor or delta < -1e-12
|
|
objective = self.envelope.promotion_rules.objective_metric
|
|
if quality_regression:
|
|
status, error_code = "STOPPED_QUALITY_REGRESSION", "OPTIMIZATION_QUALITY_REGRESSION"
|
|
elif effect[objective] + 1e-12 < self.envelope.promotion_rules.minimum_improvement:
|
|
status, error_code = "STOPPED_NO_IMPROVEMENT", "OPTIMIZATION_NO_IMPROVEMENT"
|
|
else:
|
|
status, error_code = "ELIGIBLE", None
|
|
return self._store_evaluation(row, evaluation, receipt, effect, status, error_code, candidate)
|
|
|
|
def _store_evaluation(
|
|
self,
|
|
row: sqlite3.Row,
|
|
evaluation: Mapping[str, Any],
|
|
receipt: Mapping[str, Any],
|
|
effect: Mapping[str, Any],
|
|
status: str,
|
|
error_code: str | None,
|
|
candidate: Mapping[str, Any] | None = None,
|
|
) -> dict:
|
|
candidate = dict(candidate or {})
|
|
with self._connect() as connection:
|
|
connection.execute(
|
|
"""
|
|
UPDATE optimization_proposals
|
|
SET status=?,candidate_json=?,effect_json=?,evaluation_json=?,receipt_json=?,
|
|
error_code=?,updated_at=?
|
|
WHERE proposal_id=?
|
|
""",
|
|
(
|
|
status, canonical_json_bytes(candidate).decode("utf-8"),
|
|
canonical_json_bytes(effect).decode("utf-8"),
|
|
canonical_json_bytes({k: evaluation[k] for k in evaluation if k != "receipt"}).decode("utf-8"),
|
|
canonical_json_bytes(receipt).decode("utf-8"), error_code, time.time(),
|
|
row["proposal_id"],
|
|
),
|
|
)
|
|
return self._record(self._row(row["proposal_id"]))
|
|
|
|
def promote(
|
|
self,
|
|
proposal_id: str,
|
|
promotion: Mapping[str, Any],
|
|
*,
|
|
authenticated_context: Mapping[str, Any],
|
|
) -> dict:
|
|
context = self._context(authenticated_context)
|
|
row = self._authorized_row(proposal_id, context)
|
|
if not isinstance(promotion, Mapping) or set(promotion) != {
|
|
"evaluation_task_id", "proposal_digest"
|
|
}:
|
|
raise OptimizationError("OPTIMIZATION_PROMOTION_REQUEST_INVALID")
|
|
if promotion["evaluation_task_id"] != row["evaluation_task_id"]:
|
|
raise OptimizationError("OPTIMIZATION_PROMOTION_TASK_MISMATCH")
|
|
if promotion["proposal_digest"] != row["proposal_digest"]:
|
|
raise OptimizationError("OPTIMIZATION_PROMOTION_PROPOSAL_MISMATCH")
|
|
if row["status"] == "PROMOTION_SUBMITTED":
|
|
return self._record(row)
|
|
if row["status"] != "ELIGIBLE":
|
|
raise OptimizationError("OPTIMIZATION_NOT_PROMOTABLE")
|
|
stored_receipt = self._trusted_receipt(self._decode(row["receipt_json"]))
|
|
if (
|
|
stored_receipt.get("task_id") != row["evaluation_task_id"]
|
|
or stored_receipt.get("proposal_digest") != row["proposal_digest"]
|
|
or stored_receipt.get("action") != "evaluate"
|
|
or stored_receipt.get("success") is not True
|
|
):
|
|
raise OptimizationError("OPTIMIZATION_PROMOTION_RECEIPT_BINDING_INVALID")
|
|
evaluation = self._decode(row["evaluation_json"])
|
|
if stored_receipt.get("result_digest") != _digest(evaluation):
|
|
raise OptimizationError("OPTIMIZATION_PROMOTION_QUALITY_RESULT_INVALID")
|
|
|
|
task_request = {
|
|
"schema": TASK_REQUEST_SCHEMA,
|
|
"task_id": f"optimization-promote-{proposal_id}",
|
|
"action": "promote",
|
|
"tenant_id": context["tenant_id"],
|
|
"subject_id": context["subject_id"],
|
|
"grant_id": context["grant_id"],
|
|
"mission_id": context["mission_id"],
|
|
"proposal_id": row["proposal_id"],
|
|
"proposal_digest": row["proposal_digest"],
|
|
"evaluation_task_id": row["evaluation_task_id"],
|
|
"evaluation_result_digest": stored_receipt["result_digest"],
|
|
}
|
|
try:
|
|
submission = self.submit_task(task_request)
|
|
if not isinstance(submission, Mapping):
|
|
raise OptimizationError("OPTIMIZATION_TASK_SUBMISSION_INVALID")
|
|
task_id = _identifier(
|
|
submission.get("task_id"), "OPTIMIZATION_TASK_SUBMISSION_INVALID"
|
|
)
|
|
except Exception as exc:
|
|
with self._connect() as connection:
|
|
connection.execute(
|
|
"UPDATE optimization_proposals SET status=?,error_code=?,updated_at=? WHERE proposal_id=?",
|
|
("STOPPED_PROMOTION_SUBMISSION_FAILED", "OPTIMIZATION_TASK_SUBMISSION_FAILED", time.time(), proposal_id),
|
|
)
|
|
if isinstance(exc, OptimizationError):
|
|
raise
|
|
raise OptimizationError("OPTIMIZATION_TASK_SUBMISSION_FAILED") from exc
|
|
with self._connect() as connection:
|
|
connection.execute(
|
|
"UPDATE optimization_proposals SET status=?,promotion_task_id=?,error_code=NULL,updated_at=? "
|
|
"WHERE proposal_id=? AND status='ELIGIBLE'",
|
|
("PROMOTION_SUBMITTED", task_id, time.time(), proposal_id),
|
|
)
|
|
return self.get_proposal(proposal_id, authenticated_context=context)
|
|
|
|
|
|
__all__ = [
|
|
"OptimizationController", "OptimizationEnvelope", "OptimizationError",
|
|
"canonical_json_bytes", "validate_proposal",
|
|
]
|