Deep dives into APX concepts, decision-making, and troubleshooting
Understand when APX stops search, blocks PRs, and how to resolve infra/external constraints
How APX calculates confidence margins for constraint satisfaction
Anatomy of a PackSpec and how to author custom constraint policies
APX blocks PRs and halts constraint search when it encounters conditions that prevent safe semantic verification. This document explains the blocking mechanism, how to detect it, and how to resolve it.
APX runs constraint check
Evaluate all constraints in policy pack
Does constraint fail?
NO → Continue to next constraint
YES → Check constraint metadata
Is solvability = infra OR external?
YES: Mark as blocked_by_infra=true
→ Halt search, set DECISION = BLOCK
→ Add to blockers list
NO (solvability = code):
→ Evaluate policy (PASS/WARN/BLOCK based on constraint kind)
→ Search continues
APX blocks in three scenarios:
Constraints marked with solvability: infra or solvability: external that fail evaluation.
These represent missing infrastructure dependencies (HSM/KMS, DEA gateway, etc.) that cannot be satisfied through code changes.
Constraints marked kind: hard that fail when policy mandates BLOCK on hard failures.
Hard constraints are non-negotiable requirements (e.g., encryption-at-rest, access control). Policy determines if failures block merges.
When constraint margins fall below policy thresholds and the policy is configured to block on low confidence.
Optional: Some policies treat low-confidence passing results as untrustworthy and block as a precaution.
{
"constraint_id": "DEA-1311.170",
"kind": "hard",
"solvability": "external",
"description": "DEA e-prescribing gateway required for controlled substance Rx",
"evaluation": {
"satisfied": false,
"confidence": 1.0,
"margin": 0.0
}
}APX evaluates constraint and finds satisfied: false
Checks metadata: solvability ∈ {infra, external}
Sets blocked_by_infra: true in evaluation result
Halts search, adds constraint ID to blockers[], returns BLOCK decision
$ apx check --json --policy strict-hipaa 🔍 APX Check (policy: strict-hipaa) ├─ Evaluating 47 constraints... ├─ ✓ 42 passed ├─ ⚠ 2 soft failures ├─ ✗ 1 hard failure └─ 🚫 2 infra/external blockers ❌ BLOCK: infra/external blockers → [KMS-AES256-1, HSM-FIPS-2] Cannot satisfy policy safely; fix blockers and rerun. See check.core.json for details.
APX Check Result: BLOCK (policy: strict-hipaa)
⚠️ APX blocked: infra/external blockers [KMS-AES256-1, HSM-FIPS-2] — cannot satisfy policy safely; fix blockers and rerun.
{
"decision": "BLOCK",
"blocked_by_infra": true,
"blockers": ["KMS-AES256-1", "HSM-FIPS-2"],
"hard_failures": [],
"soft_failures": [],
"artifacts": {
"core": "check.core.json",
"receipt": "check.receipt.json",
"health": "check.health.json"
}
}DEA-1311.170
DEA-certified gateway required for controlled substance prescriptions (Schedule II-V)
KMS-AES256-1, HSM-FIPS-2
Hardware security module or key management service required for encryption-at-rest
K8S-PDB-1, K8S-HPA-1
PodDisruptionBudget and HorizontalPodAutoscaler required for critical workloads
AUDIT-STORE-1
Immutable audit log storage (e.g., AWS CloudTrail, Azure Monitor) not configured
Check console output, PR comment, or check.core.json for the blockers[] array
$ jq '.blockers' check.core.json ["KMS-AES256-1", "HSM-FIPS-2"]
For each blocker, provision the required infrastructure or enable the external service
Once infrastructure is in place, run the check again. Blockers should clear.
$ apx check --json --policy strict-hipaa ✅ PASS: All constraints satisfied (policy: strict-hipaa)
Not all failures are blockers. If a constraint fails but is not marked as infra or external, APX will:
Continue search: APX will keep looking for solutions; search is NOT halted
Apply policy decision: WARN or BLOCK based on constraint kind (hard/soft) and policy rules
Provide locations: Check check.core.json for exact file locations, line numbers, and margins
Generate audit trail: See check.receipt.json for complete evaluation history
These failures are code-solvable and can be fixed through code changes, configuration updates, or annotations. Use Studio Lite to explore violations and identify fix locations.