stemedb/applications/aphoria/feature.md

Feature: Dynamic Application Policy

Codify your team's decisions as authoritative truth.

The Problem: "It Depends"

Global standards (RFCs, OWASP) are binary: TLS verification is mandatory; SQL injection is forbidden.

But most engineering decisions are contextual:

• "This legacy service must use TLS 1.2 because clients are old."
• "All services in the payment namespace must have audit logging enabled."
• "The connection pool must be capped at 50 to prevent DB saturation."

Standard linters can't enforce these because they lack context. They see min_version = "1.2" as valid syntax. They don't know that for this specific app, it's a critical policy violation (if the policy was 1.3) or a mandatory requirement (if the policy is 1.2).

The Solution: Policy as Data

Aphoria allows you to define a Local Policy Corpus. This file lives in your repo (aphoria-policy.yaml) and defines the authoritative truths for this specific project.

When Aphoria scans, it treats these rules as Tier 0 (Regulatory) — effectively overriding conflicting advice from vendors or general best practices.

Example: aphoria-policy.yaml

rules:
  # 1. Override a Vendor Default
  # Vendor says: "Default pool size is 100" (Tier 2)
  # Policy says: "We limit to 50" (Tier 0)
  - path: "code://rust/citadeldb/db/pool_size"
    predicate: "config_value"
    value: 50
    tier: "Regulatory"
    message: "Internal policy: max 50 connections to prevent potential storms."

  # 2. Enforce a Legacy Constraint
  # RFC says: "TLS 1.3 is SHOULD"
  # Policy says: "TLS 1.2 is MUST for legacy support"
  - path: "code://go/legacy-service/tls/version"
    predicate: "min_version"
    value: "1.2"
    tier: "Clinical"
    message: "Legacy clients (ATM network) require TLS 1.2 support."

  # 3. Mandate a Specific Dependency Version
  - path: "code://python/data-science/dep/pandas/version"
    predicate: "installed_version"
    value: "2.1.0"
    tier: "Regulatory"
    message: "Must use pandas 2.1.0 due to regression in 2.2.x."

How It Works

1. Ingestion: On aphoria scan, the CLI reads aphoria-policy.yaml.
2. Assertion Creation: Each rule is converted into a StemeDB Assertion with SourceClass::Regulatory (Tier 0) or SourceClass::Clinical (Tier 1).
3. Conflict Detection: The query engine compares your code's extracted claims against these new assertions.
4. Enforcement:
   • If Code says pool_size = 100 and Policy says 50 (Tier 0), the conflict score is high (BLOCK).
   • The developer gets a clear error: "Internal policy: max 50 connections..."

The Enterprise Lens

For complex organizations, Aphoria supports the Enterprise Lens. This lens automatically prioritizes:

1. Local Policy (Tier 0 Override)
2. Regulatory Standards (RFC/NIST)
3. Vendor Documentation

This ensures that "Our Truth" wins locally, without polluting the global knowledge graph. You aren't claiming "TLS 1.2 is secure globally" (which is false); you are claiming "TLS 1.2 is required here" (which is true).

Use Cases

• SRE Teams: Distribute a shared aphoria-policy.yaml template to all microservices to enforce timeouts and retries.
• Security Teams: Mandate specific crypto libraries or key rotation intervals that go beyond OWASP defaults.
• Platform Engineering: Enforce standardized ports, logging formats, and health check endpoints across polyglot repos.